Architecture for simple complementary currencies accounting

Architecture for simple complementary currencies accounting within a social network.

Intent/Audience

This document is for developers aspiring to build a mutual credit accounting ecosystem in a social network. It is a mostly platform-agnostic description of the architecture and API for the Mutual Credit module for Drupal. The core can be used with a web API for credit clearing on a remote server, or with more modules enabled, can provide all the accounting required in a Drupal-based trade exchange.

Introduction

This architecture supports mutual credit systems such as LETS, SEL, Tauschring and Timebanks. It is designed to be extendible to serve many different designs of community currency as yet unformulated. These systems are characterised by the sum of all user balances always being zero. By issuing currency from a designated account, it is possible to run a fiat or backed currency. By designating a 'cash' account, it is possible to issue paper credits.

In particular, this architecture meets the following requirements.

• An accounting system to plug into online social networks
• A configurable payment form which supports exchanges in either direction
• Optional 'signing' of exchanges by 2nd or 3rd parties.
• Credit/Debit limits, which can be controlled globally or per-user
• A rating system in which the payer rates the exchange
• The system should support an arbitrary number of currencies, with extensible properties
• There should be scope for new trading tools and transaction types, such as demurrage, auctions, loans, gift tokens, interaction with the rest of the web, and much more.

Data structure

The heart of the system is the transaction database table.

• TxID: unique identification
• Description
• Currency ID
• Payer ID
• Payee ID
• Rating (numeric)
• Quantity (int or float)*
• State (enum - finished, pending, erased, contested?)
• Transaction Type: says which module or form created the exchange
• Parent TxID: will be used for dependent transactions such as tithe/tax
• data: a serialized array of properties added by other modules

Many of these fields can be left blank as long as the transaction state isn't 'finished'. This leaves the possibility later on to store not only pending transactions, but also transactions with incomplete data all in the same table.

Then there is a second table which stores user balance info, updated after each transaction. This could also be done as a database 'view'

• User ID (Key)
• Currency ID (Key)
• Balance*
• Gross income*
• Gross expenditure*
• Any other fields you might want to access easily

Finally there is the currency table

• Currency ID
• Name
• Value: relative to other currencies in the same value framework
• Icon
• Default min balance
• Default max balance
• Data (serialised array of other properties), in this case
  • the currency colour used in visualisation
  • the currency specific rating grades with numeric values and names
  • fractions of the unit, like quarter hours with cent values and friendly names
  • any data added by other modules (see below)
• subdivision: whether an integer or float field is required

*The subdivisions are always converted to two decimal places and stored as float values. The system needs to decide whether to use float or integer storage for these values. If any currency has subdivisions, these fields will all be float values.

Permissions need to be a little more elaborate than many frameworks probably provide. the following seem about the right granularity: Exchange | View all exchanges | View all balances | Edit all exchanges | Configure economy | Declare currency. These permission assume that each user has equal permission over all currencies. For a large number of currencies, or a more elaborate system, this would need to be improved.

It can be helpful to have some way to categorise the exchanges to help in monitoring the health of the economy. A flexible category system isn't part of the transaction architecture, and is better done using a flexible tagging tool during implementation of the system.

Forms for recording exchanges

Default, 3rdparty form

This is the default because it's the simplest. The user enters the payer, payee, amount and description, and the currency if there is more than one, and the rating if applicable in that currency. AJAX is helpful to rebuild the form once the currency has been chosen, so as to show the right subdivisions and rating scale. It is also extremely useful to be able to pass partially built exchange records to the form and to hide or disable the completed fields. This can improve usabilitiy by reducing the number of fields the user has to fill. Some site architects may want an "Are you sure you want to record this exchange?" form, others may not. It may be helpful to put a minimum word limit on the exchange description expecially if you are trying to categorise it automatically.

1st party form

Most people's idea of a usable exchange form doesn't involve entering two users, one of whom is themselves. It is easier for users entering their own exchanges merely to indicate the other involved user. Because exchanges can be both incoming or outgoing (in relation to the user who creates them) the 1st party form needs a way to choose the direction, unless the software is set up to assume one direction. Therefore this module introduces 2 'exchange types' to the system, incoming and outgoing. These can be named. It's a little arbitrary but at the moment it injects these exchange types into the currencies' properties, and the 1st party form only works with currencies that have an exchange type checked. When building the form, it is necessary to convert between the inherent data structure of the exchange (payer & payee), and the data needed for the form (other user & exchange type).

Multiple exchanges forms

Sometimes it will be necessary to enter many similar exchanges at once, paying to or from a single account. Drupal provides 4 forms for this, called one2many, many2one, one2few, few2one. depending on whether the users are selected by inclusion or exclusion. The form provides an optional preview of all the exchanges, then on submission, builds a list of transactions and sends them one by one to the API above.

Signatures

The need for signatures provides another dimension to the exchange types, such that they can be presented in a 2x2 grid. Here they are with some suggested names.

	Incoming	Outgoing
Direct	Claim	Gift
Signed	Invoice	Payment

The signatures module is aware of the preceding forms and injects a checkbox into the thirdparty form and 2 more exchange types into the currency properties. When the exchange is loaded or displayed it adds links to it, depending on who is viewing, to sign the exchange. So an administrator would be able to sign it as any of the signatories, or as all of them. As with the preceding forms, the confirmation page is also optional. Presently the Drupal module doesn't affect the exchange-edit form, because it would be hard to know widget to put.

Skinning the forms

The usability and hence the flexibility of the exchange form is very important. Because of the way that Drupal renders forms by default, a 'special theming' option is provided which allows more control over the HTML of the form. This allows, for example a friendlier sentence formation, rather than the formulaic "fieldname: widget" pattern. THe form should also be able to cope with additional fields being added to the exchanges.

Default exchange form

Special exchange form

User Limits

The currency properties include an optional min/max balance which can be held. This is enough for the simplest LETS, but many systems require per-user limits. This module therefore injects min/max limits for each currency into each user's page and adds a layer of validation to the exchanges before the form validates. It also implemements a hook which allows later modules to determine what each user's balance limits are.

Stats & caching

In large systems this will need to be much better addressed. The problem is that mutual credit system need to read the whole transaction history of a user to get the balance, which can be potentially expensive. My compromise is to store the complete trading history for each user as a cached object, and then on display it has to check the access permissions for every transaction within the limits being displayed, which should be determined by date. Another way to optimise is to keep accounting periods with ending balances, so the calculation only needs to be done from the end of the last period. These matters are mostly solved problems in other realms.

Admin can configure whether stats are recalculated after every exchange or done on cron. When triggered the system works one currency at a time, loading all the exchanges and adding them to various arrays which are then cached. Some stats such as 'number of exchanges' are also derived regardless of currency.

All this cached data needs to be made available to be viewed by simple scripts. In Drupal the stats module produces blocks which are configurable by stat, currency, period and, where applicable, num of items to display e.g "Top 5 dubloon traders by volume"

User Display

This module provides the information that makes up most of the user experience. In particular, the user-specific summaries such as exchange history or current balances. Drupal puts all of these on one user tab called 'Bureau', but the intention is to spread them around where needed. It provides a visualised 'balance history' using google charts API, and a google-o-meter visualising the users balance between the maximum and minimum limits, amongst other lists and tables.

Web API

The following functions need to be available via web API. currency/create currency/retrieve currency/update currency/delete currency/list exchange/create exchange/retrieve exchange/update exchange/delete exchange/sign exchanges/user exchanges/list_since balances/user

Mail notifications

This is not a seperate module at the moment. The core provides a template with tokens to notify users that an exchange has been recorded. Users determine their own notification threshhold.

1. No notification
2. Only when my action is needed
3. When someone records an exchance involving me
4. When I or anyone records an exchance involving me

The signatures module injects an extra paragraph into the mails if a signature is required.

Planned for version 3.0 (for Drupal 7)

Swoppable accounting engine

There are some people who want to make a much more sophistated transaction engine, more like Cyclos, and have Drupal plug into that via a web api starting with the one above.

Mutual Guarantor

Users are allocated a shadow currency, which is a multiple of their last 6 months trading volume, and they allocate this to other users as an expression of trust. Then when a user defaults, the balance can be recovered automatically from the users who misplaced their trust, and not burden the whole system.

Mutual Recognition Agreements

Special accounts that communicate with other associations to coordinate payments, effectively transferring value between systems. CES is working on this already. It is a high priority that Drupal be compatible with their 200 hosted associations.

Accounts

There isn't always a 1:1 relationship between users and accounts. Currently the system assumes account 1 (like user 1 in Drupal) is special. But there is a need for more non-member accounts. Taking this idea further, the trading account numbers could be decoupled from the user IDs and users would have access control over accounts to view, payout, or sign transactions.

Leakage

Any kind of system governance needs systematic funding. Leakage can be done in two ways, periodically, and per transaction. The rules, like the tax system, can be infinitely elaborate! Leakage is also the obvious way to do digital demurrage. Users don't pay to keep the notes valid, but they can pay a negative interest on positive balances.

• By matslats at 07/20/2010 - 11:23
• mutual credit & software