FTN19.1: FutoIn Interface - Transaction Engine - Currencies Version: 1.0DV Date: 2017-12-24 Copyright: 2017 FutoIn Project (http://futoin.org) Authors: Andrey Galkin
This is sub-specification of main FTN19: Transaction Engine.
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.
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.
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.
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.
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.
CURRENCY - update of existing currencyCURRENCY_NEW - new currencyEXRATE - change of existing exchange rateEXRATE_NEW - new pair of exchange rateCurrency-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.
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" : 39
},
"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})?$"
}
}
}
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" ]
}
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=