Smart contracts documentation
Bloinx Smart contracts
Is the complete cycle of the saving circle that is divided in turns according to the number of participants.
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.
The creator of the round.
- 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.
- 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.
This factory pattern smart contract is used to
Save amount or payment per turn
Number of users size >1 && <=10
Duration of one turn in seconds
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).
contractInstance.methods.createRound(warranty, saving, groupSize, payTime,token)
The Value of childRound returns the address of the new SavingGroups smart contract. This value changes each time a round is created.
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.
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.
Stores the users address
Stores the selected turn by the user
Stores the user’s security deposit balance
Stores the user’s fund balance. Represents the deposits other users have done for this user to withdraw
Stores the user’s payments that have been assigned to other users' funds.
Stores the user’s payments that haven’t been assigned to other users' funds.
Stores the number of turns the user has not paid. The user is able to pay later but this value will not be modified
Stores how much of the security deposits has been taken because of this user's late payments.
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.
Stores the amount the user has withdrawn from the round.
The smart contract has 6 mandatory parameters shown in the following table.
Safety deposit to be paid on registration.
Payment in each turn.
Number of turns >1 && <= 10
Wallet address of the round creator, can’t be null (0x0).
Time of one turn in seconds.
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.
address user, uint turn
Executed when a user is registered to the saving round. Returns the user address and the turn.
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.
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.
address removed by, address user, bool success
Executed when a user is removed. Returns the user address and payment success.
address user , bool success
Executed when a user makes a payment to the round. Returns the user address and payment success.
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.
address round address , uint start at, uint end at
Executed when the round ended. Returns the round address and the start and end times.
Address round address, uint funds transferred
Executed when the insufficient funds are transferred to a general account. Returns user address and funds transferred.
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
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.
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.
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.
Is pay amount correct
Users can pay any amount up to all planned payments.
Is it time to withdraw for the user, has the user withdrawn
This function transfers the fund to the assigned user.
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.
If the user owes the security deposit it is taken from the assigned fund to withdraw.
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.
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)
Returns the amount the user is required to have paid at the called time.
Returns the turn according to the block time when the function is called.
Returns availableCashIn from user struct.
Returns availableSavings from user struct.
Returns assignedPaymentsfrom user struct.
Returns unassignedPayments from user struct.
Returns latePayments from user struct.
Returns owedTotalCashIn from user struct.
Returns isActive from user struct.
Verifies the current stage. Is used to limit functions to determined stages.
Verifies if the function caller is the admin. Is used to define the functions available only to the admin.
Verifies if the caller is registered on this round. Is used to define functions only available for users registered to the round.