Smart contracts documentation

Bloinx Smart contracts

Terminology

Round	Is the complete cycle of the saving circle that is divided in turns according to the number of participants.
Turn	Is one period of the saving circle. I.E In a weekly round of 5 people, the suns last 1 week and the round lasts 5 weeks.
Administrator/admin	The creator of the round.

Rules

1. Create a saving round

   1. The user that creates the saving round will have the administrator role, they must indicate the number of guests, the amount of the payment(per turn), the periodicity and invite others to participate in their round.

   2. Take into account that you will not be able to modify this data and that each guest can only register for one turn of the round.

2. Registration

   1. In the registration stage, users will be able to select a turn and must make a payment in advance as a security deposit that will be reimbursed according to payment fulfillment.

   2. The admin is responsible to verify that the registered addresses correspond to those of their guests. In case a guest is not in the correct round, they will be able to remove them.

   3. Important: once the round has started, no changes in the users is possible.

3. Payments and withdrawals

   1. When the round starts, all the guests will have the days you indicated in periodicity to make the first payment. The person on the first turn does not pay.

   2. Once the payment time has passed, the guest in the first turn will be able to collect the accumulated fund. This is repeated for the number of participants in the round.

   3. If one of your guests does not pay on time, the initial fee will be taken from them to cover their contribution for that turn.

   4. The first time a guest does not pay on time, they will not have his initial fee at the end of the round. And it will not affect the other guests.

   5. From the second time that a guest does not pay on time, they will impact the amount that all guests will receive at the end of the round.

   6. If users have pending payments, they can catch up while the round is running.

4. End of the round

   1. At the end of the round, what is in the safety deposit pool will be distributed among users with timely payments.

5. Round out of funds

   1. If several users miss payments the round could run out of funds to pay the person in turn. If this is the case, the total balance of the round smart contract will be sent to a general account.

Main.sol

This factory pattern smart contract is used to

Method	Parameters	Required	Type	Description
CreateRound	_warranty	Yes	uint	Security deposit
	_saving	Yes	uint	Save amount or payment per turn
	_groupSize	Yes	uint	Number of users size >1 && <=10
	_payTime	Yes	uint	Duration of one turn in seconds
	_token	Yes	IERC20	Token to user in the saving round

If the Round creation method is executed correctly, the function returns the address of the new smart contract (SavingGroups).

Call example:

contractInstance.methods.createRound(warranty, saving, groupSize, payTime,token)

.send({

from: userAddressWallet,

to: contractAddress

})

Response example:

[

{

"from": "0xd9145CCE52D386f254917e481eB44e9943F39138",

"topic": "0xfdebb0c30fbd3c4fe101775e6bf17ea692258188ce7edb5666366f58f1529ffc",

"event": "RoundCreated",

"args": {

"0": "0xb8f43EC36718ecCb339B75B727736ba14F174d77",

"childRound": "0xb8f43EC36718ecCb339B75B727736ba14F174d77"

}

}

]

The Value of childRound returns the address of the new SavingGroups smart contract. This value changes each time a round is created.

SavingGroups.sol

The SavingGroups.sol smart contract features the Stages Enum, enums are a way to create user-defined data types and are implicitly convertible to integers.

Enum Name	Value	Description
Stage	Setup -> 0	In this stage the users register to the saving round. And the admin is able to start the round.
	Save -> 1	In this stage the users are able to make payments and withdrawals according to the registration order. No changes in the user list are possible at this stage.
	Finished -> 3	When the time of the last turn has passed, the saving round can pass to this stage. In this stage the calculation of the security deposit returns is done. No more payments are allowed at this stage.
	Emergency -> 4	If there are no funds for a withdrawal, the round enters in this stage to indicate the round did not end correctly. The available balance in the SC can be sent to a general account.

The smart contract features a struct with the user information so the smart contract can manage the round correctly. The users are stored in a mapping.

Struct Name	Parameters	Type	Description
User	userAddr	address	Stores the users address
	userTurn	uint	Stores the selected turn by the user
	availableCashIn	uint	Stores the user’s security deposit balance
	availableSavings	uint	Stores the user’s fund balance. Represents the deposits other users have done for this user to withdraw
	assignedPayments	uint	Stores the user’s payments that have been assigned to other users' funds.
	unassignedPayments	uint	Stores the user’s payments that haven’t been assigned to other users' funds.
	latePayments	uint	Stores the number of turns the user has not paid. The user is able to pay later but this value will not be modified
	owedTotalCashIn	uint	Stores how much of the security deposits has been taken because of this user's late payments.
	isActive	bool	Variable to indicate if the user is registered. If a user registers and is removed, the user is still in the User mapping but has this variable set to false.
	withdrewAmount	uint	Stores the amount the user has withdrawn from the round.

The smart contract has 6 mandatory parameters shown in the following table.

Method	Parameters	Type	Description
constructor	_cashIn	uint	Safety deposit to be paid on registration.
	_saveAmount	uint	Payment in each turn.
	_groupSize	uint	Number of turns >1 && <= 10
	_admin	Address payable	Wallet address of the round creator, can’t be null (0x0).
	_payTime	uint	Time of one turn in seconds.
	_token	IERC20	Token address to be used in the saving round.

The constructor is executed only once in the smart contract deployment, that comes from the CreateRound function in Main.sol.

Inside the constructor the amounts of _saveAmount and _cashIn are converted to the unit of wei.

The constructor has 3 main validations:

1. Validates that the administrator address is non-zero or null.

2. Validates that the group size is greater than one and less than or equal to ten.

3. Validates that the time given by the user is greater than zero and is multiplied by the seconds in a day.

Example: _payTime = 2 -> 2 * 86,400 = 2 days.

Events within Saving Groups.

Events are a simplified way of sending information to external systems like a frontend or a subgraph.

Event	Parameter	Description
RegisterUser	address user, uint turn	Executed when a user is registered to the saving round. Returns the user address and the turn.
PayCashIn	address user, bool success	Executed when a user is registered to the saving round and the safety deposit is paid. Returns the user address and payment success.
PayFee	address user, bool success	Executed when a user is registered to the saving round and the fee is paid. Returns the address of the remover, user address and payment success.
RemoveUser	address removed by, address user, bool success	Executed when a user is removed. Returns the user address and payment success.
PayTurn	address user , bool success	Executed when a user makes a payment to the round. Returns the user address and payment success.
WithdrawFunds	address user , uint amount, bool success	Executed when a user whidraws the fund corresponding to their turn. Returns the user address, withdrawn amount and payment success.
EndRound	address round address , uint start at, uint end at	Executed when the round ended. Returns the round address and the start and end times.
EmergencyWithdraw	Address round address, uint funds transferred	Executed when the insufficient funds are transferred to a general account. Returns user address and funds transferred.

Fee Cost.

The fee cost is currently calculated in the constructor:

feeCost = (saveAmount / 10000) * 500;

It corresponds to 5%. And it is transferred to the Team Bloinx wallet

Methods table

Method	Parameters	Type	Modifier	Validations	Description
registeUser (public)	_userTurn	uint	atStage	Is user already registered, Is group already full, is turn taken	User inputs the turn for registration ion the round. The user must have already approved the token smart contract.
removeUser (public)	_userTurn	uint	atStage	If the caller is the admin, is the turn empty, is the deleted user the admin	Admin can remove users before in the SetUp stage.
stratRound (public)			onlyAdmin atStage	Is group full	When all the turns are taken, the admin can start the round. This function advances the stage to Saving. The block time is recorded as the start time of the round from which the turns start counting. No changes in the registered accounts are allowed once this function is executed.
addPayment (external)			isRegisteredUser atStage	Is pay amount correct	Users can pay any amount up to all planned payments.
withdrawTurn (public)			isRegisteredUser atStage	Is it time to withdraw for the user, has the user withdrawn	This function transfers the fund to the assigned user.
completeSavingsAndAdvanceTurn (private)	turn	uint	atStage		Called from addPayment, withdrawTurn and endRound. Executed once in a turn by each user. Transfers funds to the corresponding variables of User and advances turn if the time determines it should.
payLateFromSavings (private)	_userAddress	address	atStage		If the user owes the security deposit it is taken from the assigned fund to withdraw.
emergencyWithdraw (public)			atStage	Is stuck balance more than cero	If the round is out of funds to make payments the stuck balance can be sent to a general account.
endRound			atStage	Is the round finished	Transfers the corresponding amount of the security deposit to each user
futurePayments (public) (view)					Returns the total amount left to pay in the round by the caller
obligationAtTime (public) (view)	userAddress	address			Returns the amount the user is required to have paid at the called time.
getRealTurn (public) (view)					Returns the turn according to the block time when the function is called.
getUserAvailableCashIn (public) (view)	_userTurn	uint			Returns availableCashIn from user struct.
getUserAvailableSavings (public) (view)	_userTurn	uint			Returns availableSavings from user struct.
getUserAmountPaid (public) (view)	_userTurn	uint			Returns assignedPaymentsfrom user struct.
getUserUnassignedPayments (public) (view)	_userTurn	uint			Returns unassignedPayments from user struct.
getUserLatePayments (public) (view)	_userTurn	uint			Returns latePayments from user struct.
getUserOwedTotalCashIn (public) (view)	_userTurn	uint			Returns owedTotalCashIn from user struct.
getUserIsActive (public) (view)	_userTurn	uint			Returns isActive from user struct.

Modifiers table

Method	SC	Parameters	Type	Description
atStage	SavingGroups.sol	_stage	Stages	Verifies the current stage. Is used to limit functions to determined stages.
onlyAdmin	Modifiers.sol	admin	address	Verifies if the function caller is the admin. Is used to define the functions available only to the admin.
isRegisteredUser	Modifiers.sol	user	bool	Verifies if the caller is registered on this round. Is used to define functions only available for users registered to the round.