Collateral Module

Goals

Implement a module that deals with collateral as an independent and dynamic entity of the Mifos X core system.
Remove the current tight coupling between loans and collaterals.

Background

The collateral module currently implemented is a very basic and limited implementation. Currently the implementation expects a loan entry to be already presented in the system to create a corresponding collateral for that loan. This leads to 1-1 mapping between the collaterals and loans. This means that every time a new collateral has to be defined even when an exact same collateral scheme already exists with another loan. This leads to huge amount of data duplication. Also a user interested in wanting to research the different collaterals options available before taking a loan cannot do so.

By developing the collateral module we will maintain the collaterals as a separate entity. This way a single collateral definition can be associated with multiple loans. The base price of the underlying security can be adjusted dynamically without affecting the loan products. The user will also have an option to custom build a collateral as a combination of several individual collateral definitions. Even the financial institutions will have the option to roll out various collateral schemes based on specific use cases.

DB Design

Foreign Keys:

`m_loan_collateral`.`collateral.id` Refers `m_collateral`.`id`

`m_collateral`.`base_id` Refers `m_collateral_base_value`.`id`

`m_collateral_base_value`.`type_cv_id` Refers `m_code_value`.`id`

Columns (Explanation)

m_collateral_base_value

Column

Meaning

type_cv_id

Thee code value table id of the particular collateral

base_price

The base unit price of the collateral (eg: 31000 for (10 grams)gold, Rs. 5000/sq ft for real estate etc.)

The base unit is pre decided.

m_collateral

Column	Meaning
base_id	id in the m_collateral_base_value table for the particular base definition of a collateral
quality_standard	Quality description (24 carat, 20 carat etc. for gold)
pct_to_base	Quality value of the collateral as a percentage of the base quality ( 24(100%) carat, 20(83.33%) carat etc. for gold )

The m_collateral_base_value will mention the current market value of any collateral. It can be changed dynamically. For example If the Current market price of gold is 31k/10 grams, we will create an entry for gold collateral in m_code_value , refer it in the m_collateral_base_value and store 31k in the `m_collateral_base_value`.`base_price` column. This is the base value which will be used for all gold based collaterals created .

The m_collateral table stores the actual collateral definition. For example if we want to store the definition of 24 carat gold, The `m_collateral`.`base_id` will store the `m_collateral_base_value` table id for the gold price entry. The `m_collateral`.`quality_standard` will store the definition of the collateral (24 carat in this case). The `m_collateral`.`pct_to_base` is the percentage value w.r.t. the base price of that collateral. 24 carat gold being the purest form will have this value as 100.0 (100%). Other definitions such as 22 carat will have values less than 100.0 in this column. In case of collaterals such as real estate there is no definition of purity as such, hence all collateral definitions will have 100.0 value in the `pct_to_base` column.

Basic Algorithm for Collateral value calculation

Payload giving the list of collaterals to be considered

"collateralDetails":[{

"units":"3",

"collateralId":"5"

},

{

"units":"5",

"collateralId":"6"

}]

collateralId: id value of m_collateral table for a particular collateral definition.

units: This is the number of units to be used for the collateral corresponding to the collateralId. Eg: 3 units of gold will mean (3*10) 30 grams of gold.

Basic Algo

For example let collateralId 5 correspond to 24 carat gold with base price 31k and collateralId 6 be real estate. If the base unit of gold is 10g then 2 units will be 20 grams, If real estate in 100 sq ft then 5 units will be 500 sq ft. The loan amount will be done as follows

1. First get the collateral entry from `m_collateral` using collateralId. From that entry get the pct_to_base(percentage to base) and base_id.

2. Using base_id get the base value from the `m_collateral_base_value` table.

3. Multiple units*base_value*pct_to_base/100 . This will be the value of that collateral.

4. Using the above strategy calculate the collateral values for all the collaterals in the above given JsonArray and add of them.

5. This will give the net collateral amount of the list of collaterals mentioned.

Sample Collateral Data for given loanId

[
 {
 "id": 6,
 "collateralDetails": {
 "codeValueName": "Gold Loan",
 "quality": "22 carat",
 "basePrice": 12.75,
 "pctToBase": 77.5
 },
 "value": 29.64375,
 "quantity": 3,
 "currency": {
 "code": "USD",
 "name": "US Dollar",
 "decimalPlaces": 2,
 "displaySymbol": "$",
 "nameCode": "currency.USD",
 "displayLabel": "US Dollar ($)"
 }
 },
 {
 "id": 7,
 "collateralDetails": {
 "codeValueName": "Gold Loan",
 "quality": "24 carat",
 "basePrice": 12.75,
 "pctToBase": 80
 },
 "value": 51,
 "quantity": 5,
 "currency": {
 "code": "USD",
 "name": "US Dollar",
 "decimalPlaces": 2,
 "displaySymbol": "$",
 "nameCode": "currency.USD",
 "displayLabel": "US Dollar ($)"
 }
 },
 {
 "id": 11,
 "collateralDetails": {
 "codeValueName": "Gold Loan",
 "quality": "trial quality",
 "basePrice": 12.75,
 "pctToBase": 75
 },
 "value": 57.375,
 "quantity": 6,
 "currency": {
 "code": "USD",
 "name": "US Dollar",
 "decimalPlaces": 2,
 "displaySymbol": "$",
 "nameCode": "currency.USD",
 "displayLabel": "US Dollar ($)"
 }
 }
]

Implementation till now

https://github.com/karthikiyer/incubator-fineract/tree/collateral-module

The above design is under review and will go through multiple changes which will be reflected in this document.