Overview

Implements main account. Like every other account, there is a validation in pre-posting hook to ensure that balance on DEFAULT address is always more or equal to zero.

Parameters

Name	Type	Default	Description
blocked_by_bank	Instance	false	Blocked by bank parameter. Rejects all transactions (both incoming and outgoing) if true. (Options: false, true)
blocked_by_client	Instance	false	Blocked by client parameter. Rejects all outgoing transaction if true. (Options: false, true)
deposit_interest_wht_account	Template	DEPOSIT_INTEREST_WHT_ACCOUNT	Internal account for paid interest tax. Note: Should be removed when Postings library will be implemented.
overdraft_repayment_transaction_type	Template	OVERDRAFT_REPAYMENT	Transaction type that specifies overdraft repayment
overdraft_allowed_transaction_types	Template	["INTERNAL_TRANSACTION", "BILL_PAYMENT", "CARD_PAYMENT", "OVERDRAFT_FEE"]	Transaction types allowed for use in overdraft. Json with list of transaction types.
rounding_difference_account	Template	ROUNDING_DIFFERENCE_ACCOUNT	Internal account for rounding difference when closing pockets. Note: Should be removed when Postings library will be implemented.
deposit_interest_cost_account	Template	DEPOSIT_INTEREST_COST_ACCOUNT	Internal account for paid interest balance. Note: Should be removed when Postings library will be implemented.
interest_application_second	Tempalte	0	The second of the minute at which profit is applied.
interest_application_minute	Tempalte	5	The minute of the hour at which profit is applied.
interest_application_hour	Template	1	The hour of the day at which profit is applied.
interest_accrual_second	Template	0	The second of the minute at which profit is accrued.
interest_accrual_minute	Template	0	The minute of the hour at which profit is accrued.
interest_accrual_hour	Template	1	The hour of the day at which profit is accrued.
template_interest_rate	Template	0.001	Annual interest rate for main account
debug	Instance	-	Debug parameter used for rescheduling of the events.
denomination	Template	PHP	Default denomination.
reduced_interest_rate	Global	0.0001	Reduced interest rate applied for pockets.
interest_limit	Global	0.01	Interest limit applied for pockets.
interest_tax_rate	Global	0.2	Tax rate applied for accrued interests.

Addresses

Name	Rounding digits number	Description
DEFAULT	2	Customers money on the account.
OVERDRAFT	2	Available remaining overdraft. The total amount taken as overdraft if tracked by Loans squad.
INTEREST	5	Accrued interest not paid to the customer. Accrued on daily basis, applied (given to the customer) once per month
WTH	5	Accrued withholding tax. This amount will be payed by the customer during interest application.
FEE	2	Fee

Note: Rounding is as it should be, not as it is at the moment

Transactions

Event	Name	Debit account	Credit account	Product	Note
Daily interest accrual	Interest accrual	Deposit interest cost account	Main account/ INTEREST	Main account interest	Shown in interest history as gained interest
Daily interest accrual	Withholding tax accrual	Main Account/ WHT	Deposit interest WHT	Main account interest	Shown in interest history as paid tax
Monthly interest application	Interest application	Main account/ INTEREST	Main account/ DEFAULT	Main account interest	Shown in transaction history
Monthly interest application	Tax deduction	Main account/ DEFAULT	Main account/ WHT	Main account interest	Shown in transaction history
Overdraft open/top-up	Overdraft imbursement	Overdraft Principal Receivables	Main account/ OVERDRAFT	Overdraft	Performed by Loans squad.
Overdraft closing	Overdraft repayment (total balance)	Main account/ DEFAULT	Overdraft Principal Receivables	Overdraft	Performed by Loans
Overdraft closing	Clearing of overdraft address	Main account/ OVERDRAFT	Main account/ DEFAULT	Overdraft	When we accept transaction above, we perform this transaction.
Ovedraft usage	Replenishment	Main account/ OVERDRAFT	Main account/ DEFAULT	Overdraft	In reaction to any transaction that use overdraft.

Events

Name	Scheduled at	Description
ACCRUE_INTEREST	Daily at 01:00:00
APPLY_ACCRUED_INTEREST	First day of month at 01:05:00

Overdraft

The logic of overdraft is covered by:

main account’s smart contract, where overdraft is added as a feature and its logic handling is mostly covered in:
- pre posting hook to validate if a payment is allowed for overdraft
- post posting hook where the rebalancing / overdraft repayment logic is implemented
loan manager service, where the business logic of overdraft’s life cycle is implemented using Temporal workflow

Money available for overdraft is held on main account’s address OVERDRAFT where they are transferred by Loans squad during overdraft opening via Overdraft imbursement transaction. The total amount taken as overdraft if tracked by Loans squad, we only keep track on what is remaining part.

The usage is implemented as follows. We allow transactions from list overdraft_allowed_transaction_types to reduce DEFAULT address into negative balance up to balance on OVERDRAFT address. In post posting hook we transfer enough balance via Replenishment transaction from OVERDRAFT address into DEFAULT to put it to zero balance.

Closing of the overdraft is initiated by Loans squad by taking money from DEFAULT address with Overdraft repayment transaction. We allow this transaction to reduce DEFAULT address to negative balance. In post posting hook we transfer all remaining balance from OVERDRAFT address into DEFAULT via Clearing of overdraft address transaction.

Loan’s part of the documentation for the overdraft can be found here: Overdraft Technical documentation

Blocking

There are two types of blockings - initiated by the bank and initiated by the customer. Both are enabled by setting associated instance parameter to true. If blocked_by_bank is enabled, all transactions (both outgoing and incoming) are rejected. If blocked_by_client is enabled, all outgoing transactions are rejected.

There are transactions that should not be rejected even when blocked (both types) - ones related to interests (Interest accrual, Withholding tax accrual, Interest application, Tax deduction) and payment of subscription fee (TODO: fill name here).

Interests and withholding tax

Accrual

Interest and withholding tax are accrued on daily basis via transactions Interest accrual and Withholding tax accrual on INTEREST and WHT addresses during ACCRUE_INTEREST event. The amount is computed as:

daily_interest_rate = template_interest_rate / number of days in given year
daily_reduced_interest_rate = reduced_interest_rate / number of days in given year
principal = balance on DEFAULT address
full_interest = min(interest_limit, principal) * daily_interest_rate
reduced_interest = max(principal - interest_limit,0) * daily_reduced_interest_rate
total_interest = full_interest + reduced_interest
total_wht = total_interest * interest_tax_rate

# Results
accrued_interest = round_down(total_interest, 5)
accrued_wht = round_down(total_wht, 5)

Application

On first day of the month, the interests are given to the customer (Interest application transaction) and customer virtually pays the tax (Tax deduction transaction, from financial perspective, we pay it for him/her and he did not receive it). Both of these transactions are necessary because of statements and transaction history. Both of the transaction have amount rounded to two decimal places, because on DEFAULT address we should not have number with higher precision.

applied_interest = round_down(balance on INTEREST address, 2)
deduced_wht = round_down(balance on WHT address, 2)

Note: There was a discussion in saving accounts that after application both addresses should be cleared of reminder < 0.01 into some rounding internal account. Main accounts were not mentioned - please check it!

Example

daily_interest_rate = 0.02

interest_tax_rate = 0.2

Date	DEFAULT	INTEREST	WHT
28.1.	100	2 (+2)	-0.4 (-0.4)
29.1.	100	4 (+2)	-0.8 (-0.4)
30.1.	100	6 (+2)	-1.2 (-0.4)
31.1.	100	8 (+2)	-1.6 (-0.4)
1.2.	108 (10 moved from INTEREST, 2 moved to WHT)	0 (+2, 10 moved to DEFAULT)	0 (-0.4, 2 moved from DEFAULT)
2.2.	108	2.16 (+2.16)	-0.432 (-0.432)

SaFi Bank Space : Main account smart contract