Welcome to the developer documentation for the IntegralCES project.This documentation is permanently under construction and we will complete as is necessary to us.

About

Integral CES is a suite of Drupal modules featuring social currencies management for communities. See integralces.net http://www.integralces.net for more documentation and demo.integralces.net http://demo.integralces.net for a demonstration site.

Initializing an exchange group

Visit new exchange form https://www.integralces.net/ces/bank/exchange/new and initialize the first exchange group. You must fill in the Administrator section with the user that will be the exchange administrator (It cannot be the current Drupal admin).

Visit admin exchanges page /ces/admin/ces , click on the new exchange and activate it. Login as exchange administrator and write some welcoming blog posts.

Invite the users to create an account

Users can sign up and create a new account visiting /user/register/exchange_name/ , where exchange_name is the short name of the new exchange group (Four numbers or uppercase letters)

Publish some offers and wants, blog entries... And have fun!

Base module CES

The root module is called ices. This module alone does not provide any feature to the final user. It has a pair of objectives:

It is a container for all other modules in a parent folder so ease the installation and upgrade.
Provide some shared libraries to be used by any of the submodules.

The files that directly belong to the root module are include the mandatory ces.info and ces.module and the shared libraries. Currently there is one shared library. It consists on a database abstraction layer located in file commons.db.logic.inc.

Database

There is a common way to access Drupal database within all the CES sub-modules. It is an approximate version of the active record pattern. The objective of this layer is to concentrate all the database work in a single standardized place. It isolates other code from the Drupal database layer and those it eases bug detection, permits a centralized catching system and makes the adaptation to Drupal API changes almost trivial. This common interface enterely defined in the file commons.db.logic.inc. This file defines several classes:

IcesDBObject: The abstract class that any persistent object must extend. For example, the class Exchange extends DBObject. For each class extending DBObject there is a table in the database. This class has a crucial property called table. A child class must set this variable to the table name associated with it. It also have default implementations for the two methods that convert the internal object variables into an associative array to be saved and vice-versa. By default object public properties will become table fields.
IcesSerializer: This class has methods to save, update, load and delete any object of type DBObject. It is the actual bridge with the Drupal database layer. Beyond the basic CRUD interface, it provides some other helper methods It also features a special serialization strategy for hierarchies of classes implementing the decorator pattern.
IcesLockSerializer: This is a subclass of Serializer for those operations that are delicate due to concurrency. This class assures that when you load an object, it won't be loaded by any other LockSerializer until you save it.
IcesDBTransaction: An empty wrapper for Drupal transaction.

Base de datos

Module CES Bank

CES Bank is the main banking module. It defines and works with all banking objects: exchange groups (exchages from now), accounts, transactions...

This module is divided in two parts:

The bank API is the responsible of doing all the banking logic. It is located at the ces_bank.logic.inc. It has a public interface to create accounts, do transactions etc.
The bank module is properly the Drupal module with its .info and .module files and other files for pages and forms. It uses the bank API to perform the actions ordered from the web user interface.

IntegralCES Bank API

The Bank API contains all the logic of account management. It is organized in a set of classes. There is only one public class that acts at the same time as a controller for the whole set and as the public interface. All other classes are private and should not be used from outside the file. Even the public parameters of Bank class aren't of any of the other those class types.

Bank API should be thought as an external library. In particular, it is independent of Drupal. By the way it could be used in integrations within other platforms. It uses the database access functions from the CES root module and it uses the messaging features from the CES notify module. Below is discussed the principal classes and their properties.

CesBank: Public interface for all features provided for this API. The parameters and the return values of this class are, when structured data is needed, associative arrays. The work is deferred to the concrete private objects. A typical function implementation in this class is to receive and (minimally) parse the input, create the appropiate private object, call this object's correct function, (minimally) parse the result, and return it to the caller.
CesBankExchange: Represents an exchange group of trade. It has a name, a 4-letter code, and some configurable options.
CesBankAccount: It is an interface representing a banking account. Currently there is only one implementation of this interface. It is expected for the future to use this interface also for remote hosted accounts.
CesBankLocalAccount: Implementation of Account for accounts stored in local database. An account belongs to a particular exchange. Every one has a unique identifier, started with the 4-letter code of its exchange followed by 4 numbers. Special accounts can end with 4 letters instead of numbers. Every LocalAccount is potentially related to one or more users, and every user can have one or more accounts of this type. Each account has also a LimitChain, which determines the credit and debit (and other) limits for this particular account.
CesBankAccountLimit: Atomic abstract limit for an account. It is the building block for LimitChains.
- AbsoluteDebitLimit: Limits the total debit of an account.
- AbsoluteCreditLimit: Limits the total credit of an account.
CesBankLimitChain: An ordered set of AccountLimit, identified with a name. Every account has a link to an object of this type. An account satisfies a CesBankLimitChain: if it satisfies all its AccountLimits. An exchange can configure several LimitChains for several types of accounts. For example, one 'default' for new members, one 'organization' for shared accounts that need more flexibility and one 'public' for public accounts without any limit.
CesBankTransactionInterface: Interface for the transaction between two accounts. It has methods for accessing both account codes, the amount and the description or concept of the transaction. Several implementations exist using a decorator pattern scheme.
CesBankBasicTransaction: Transaction between two accounts of the same exchange.
CesBankDecoratedTransaction: Abstract transaction which delegates all methods to a 'parent' transaction that contains as a property. This class can be inherited to add functions to a transaction.
CesBankInterexchangeTransaction: Child of DecoratedTransaction to allow trading between accounts of distinct exchanges. (Still in development)

Transaction lifecycle

Transactions have only two operations: apply a new transaction and revoke a previously applied one. However, a transaction will go through several states between the creation and the effective and irreversible application. This lifecycle is summarized in the diagram below that will now be described state by state.

NEW: Initial state. The transaction has been created but hasn't already been triggered to apply. This is the state while the transaction can be edited. Waiting for the user to apply this transaction.
TRIGGERED: The transaction has been triggered to be applied. Immediately after it asks acceptance from all pertinent authorities. It is waiting for their response. It will become ACCEPTED or REJECTED.
ACCEPTED: The transaction has been accepted by all authorities. It is being effectively applied by the system. This state is very short-lived in local transactions. The following state will be COMMITTED or ERROR if system fails to apply the transaction -for instance, a remote server couldn't respond.
COMMITTED: The transaction is successfully applied. It can however be revoked. If there aren't issues for this transaction after a prudencial time, it will be archived.
ARCHIVED: The transaction is archived and successfully applied. Nothing can be done with it. It exists only as historical data.
REJECTED: The transaction -previously triggered to be applied- has been rejected by some of the authorities. It will be discarded after a prudential time. It can sill become ACCEPTED if some authorities rectify.
DISCARDED: The transaction is discarded and has not been applied. Nothing can be done with it. It exists only as historical data.
ERROR: Some system error occurred while applying or revoking the transaction. The administrator should take care of it.

These were the distinct states a transaction may pass through while being applied. The following are those states related with the revoke operation. The starting state of the revoke operation is the COMMITTED state.

REVOKE TRIGGERED: The transaction has been triggered to be revoked. Waiting for acceptance of this operation by all authorities.
REVOKE ACCEPTED: The revoke operation has been accepted by all authorities. The system is effectively revoking the transaction. This state is very short-lived state in local transactions. The following state will be REVOKED or ERROR if system fails to revoke the transaction.
REVOKE REJECTED: Some authorities did not accept the revoke operation. The transaction will remain applied and it will be ARCHIVED after a prudential time.
REVOKED: The transaction has been successfully revoked. It will become DISCARDED after a prudential time.

The transaction state is changed using the setState() function of the Transaction interface. This function also triggers the appropriate actions. For instance, when the state is changed from TRIGGERED to ACCEPTED, it starts the effective application of the transaction.

Estados de las transacciones

CES Bank module class diagram

Class diagram for the banking module. It is an approximation of the actual implementation: there are many more properties and methods, and some of them may have distinct names. However, the architectural essence is correct.

Diagrama de clases