FTN19.1: FutoIn Interface - Transaction Engine - Currencies
Version: 1.0DV
Date: 2017-12-24
Copyright: 2017 FutoIn Project (http://futoin.org)
Authors: Andrey Galkin

CHANGES

1. Intro

This is sub-specification of main FTN19: Transaction Engine.

2. Concept (Currencies)

2.1. Codes

There are known internationally accepted currencies with standardized codes, but that does not cover widely known, but "unofficial" currencies. It's possible to have various other virtual or closed loop currencies. Therefore, there must be a clear distinction of currency code "sets". In current implementation, currency code is prefixed with the following:

It should be possible to disable unused or undesired currencies even if those were previously registered and/or used for accounts and transactions.

2.2. Units

Each currency must have a minimal unit in decimal notation. All currency operations must always have exact number of decimal places after dot in amounts used in interface. However, internal database representation may use types without decimal places after dot based on minimal unit per currency.

2.3. Exchange rates

Currency exchange rates are dynamic. Therefore, transaction engine must manage current exchange rate and full history of changes, if applicable. However, each transaction must contain used rate regardless of data available elsewhere.

It's assumed that exchange rates are constantly updated from authoritative source.

Exchange rate must be set with up to four extra decimal places after dot.

2.4. Base currency

Each currency may have own authoritative source of exchange rates. It may happen that the same currency pair may have different rates based on authoritative source.

Due to legislation and other means, all conversion operations should specify the base currency. Only associated authoritative source exchange rate must be used in such operation.

2.5. Buy/Sell margin & rounding

Due to imposed risks and rounding errors, the transaction engine operator may need to specify different rates for conversion to and from base currency. The system should hold a spot rate and a margin rate to be added to/subtracted from the spot rate.

Relative spread calculations to be done externally before spot & margin rate is set.

Rounding must be done in favour of transaction engine operator.

2.6. Events

3. Interface (Currencies)

Currency-related services are assumed to be a separate module. In some cases, there can be a single centralized service from which other instances sync. Therefore there is a strict separation between management and information retrieval.

3.1. Types

Common types in scope for currency processing.

    {
        "iface" : "futoin.currency.types",
        "version" : "{ver}",
        "ftn3rev" : "1.7",
        "types" : {
            "CurrencyCode" : {
                "type" : "string",
                "regex" : "^((I:[A-Z]{3})|([CKL]:[A-Za-z0-9*.-_]{1,16}))$",
                "desc" : "T:Code, see the spec"
            },
            "DecimalPlaces": {
                "type" : "integer",
                "min" : 0,
                "max" : 8
            },
            "CurrencyName" : {
                "type" : "string",
                "minlen" : 1,
                "maxlen" : 64
            },
            "CurrencySymbol" : {
                "type" : "string",
                "minlen" : 1,
                "maxlen" : 18
            },
            "Currency" : {
                "type" : "map",
                "fields" : {
                    "code" : "CurrencyCode",
                    "dec_places" : "DecimalPlaces",
                    "name" : "CurrencyName",
                    "symbol" : "CurrencySymbol",
                    "enabled" : "boolean"
                }
            },
            "CurrencyList" : {
                "type" : "array",
                "elemtype" : "Currency",
                "maxlen" : 1000
            },
            "ExRate" : {
                "type" : "string",
                "regex" : "^[0-9]{1,12}(\\.[0-9]{1,12})?$"
            }
        }
    }

3.2. Management

Currency management API.

    {
        "iface" : "futoin.currency.manage",
        "version" : "{ver}",
        "ftn3rev" : "1.7",
        "imports" : [
            "futoin.ping:1.0",
            "futoin.currency.types:{ver}"
        ],
        "funcs" : {
            "setCurrency" : {
                "params" : {
                    "code" : "CurrencyCode",
                    "dec_places" : "DecimalPlaces",
                    "name" : "CurrencyName",
                    "symbol" : "CurrencySymbol",
                    "enabled" : "boolean"
                },
                "result" : "boolean",
                "desc" : "Register or update currency",
                "throws" : [
                    "DecPlaceMismatch",
                    "DuplicateNameOrSymbol"
                ]
            },
            "setExRate" : {
                "params" : {
                    "base" : "CurrencyCode",
                    "foreign" : "CurrencyCode",
                    "rate" : "ExRate",
                    "margin" : "ExRate"
                },
                "result" : "boolean",
                "throws" : [
                    "UnknownCurrency"
                ]
            }
        },
        "requires" : [ "SecureChannel" ]
    }

3.3. Information

Currency information API.

    {
        "iface" : "futoin.currency.info",
        "version" : "{ver}",
        "ftn3rev" : "1.7",
        "imports" : [
            "futoin.ping:1.0",
            "futoin.currency.types:{ver}"
        ],
        "types" : {
            "ListOffset" : {
                "type" : "integer",
                "min" : 0
            }
        },
        "funcs" : {
            "listCurrencies" : {
                "params" : {
                    "from" : {
                        "type" : "ListOffset",
                        "default" : 0
                    },
                    "only_enabled" : {
                        "type" : "boolean",
                        "default" : false
                    }
                },
                "result" : "CurrencyList"
            },
            "getCurrency" : {
                "params" : {
                    "code" : "CurrencyCode"
                },
                "result" : "Currency",
                "throws" : [
                    "UnknownCurrency"
                ]
            },
            "getExRate" : {
                "params" : {
                    "base" : "CurrencyCode",
                    "foreign" : "CurrencyCode"
                },
                "result" : {
                    "rate" : "ExRate",
                    "margin" : "ExRate"
                },
                "throws" : [
                    "UnknownPair"
                ]
            }
        },
        "requires" : [ "SecureChannel" ]
    }

=END OF SPEC=