Fair Squares Design & Architecture
This section explains the mechanics of each Fair Squares pallet and runtime. A scenario derived from the testing guide is used to make the explanation easier to understand. The descriptions given reflect the current stage of development, and will be subject to changes in the future. The focus will be on user experience and future investors, for this reason, some technical aspects might be ignored.
1) Characters
The roles are distributed as follows: 1 Servicer, 1 Seller, 1 Notary, 1 Representative applicant, 2 dummy Representatives (set by default), 2 Tenant applicants, and 8 Investors. For more details on each character, see Table 1 below.
| Name | Role | Contribution to the Fair Squares Fund |
|---|---|---|
| Alice | Servicer/Council_member/Administrator | None |
| Bob | Seller/Council_member | None |
| Charlie | Notary/Council_member | None |
| Dave | Representative (Applicant) | None |
| Henry | Representative (No Asset) | None |
| Gabriel | Representative (No Asset) | None |
| Eve | Tenant (Applicant) | None |
| Ferdie | Tenant (Applicant) | None |
| KillMonger | Investor | $6,000,000 |
| Aluman | Investor | $9,000,000 |
| Shikamaru | Investor | $3,500,000 |
| Geraldo | Investor | $8,000,000 |
| Obito | Investor | $5,000,000 |
| Hans | Investor | $7,000,000 |
| Alice//stash | Investor | $3,000,000 |
| Bob//stash | Investor | $2,000,000 |
Table 1: Description of the different characters.
2) Roles Pallet
The first step in the workflow is to set roles using the Roles pallet. Users use the set_role function to apply to the role they want:
Investors & Tenants get the role right away.
Seller/Notary/Servicer/Representative
They need to go through an approval that varies with the requested role. Their request is therefore sent to a waiting list first.
Administrator & Council member are attributed by default and are not completely managed by the
Rolespallet.We will refer to them as special roles, and other roles will be referred to as standard roles. In a production environment, these will be appointed with governance. Each user can only have one standard role.
The maximum number of roles that can be attributed is currently fixed at 200.
Alice, as the platform administrator, possesses the Servicer role by default.
As a servicer, her role is to review, approve or reject Seller, Servicer and Notary role requests by using the
account_approvaland/oraccount_rejectionfunctions.She can also transfer her Administrator role to someone else (she will then lose it) by using the
set_managerfunction.
In Table 2, we give an overview of the information & actions linked to each role. The Available actions section of this table will be updated for each pallet:
| Servicer | Seller | Notary | Representative | Investor | Tenant | |
| Available Fields/Information | ||||||
| account_id | ◎ | ◎ | ◎ | ◎ | ◎ | ◎ |
| age | ◎ | ◎ | ◎ | ◎ | ◎ | ◎ |
| activated | ◎ | ◎ | ◎ | ◎ | ✖ | ✖ |
| verifier | ◎ | ◎ | ◎ | ✖ | ✖ | ✖ |
| assets_accounts | ✖ | ✖ | ✖ | ◎ | ◎ | ◎ |
| rent | ✖ | ✖ | ✖ | ✖ | ✖ | ◎ |
| Available Actions | ||||||
| Approve/Reject a role request | ◎ | ✖ | ✖ | ✖ | ✖ | ✖ |
| Set a role | ◎ | ◎ | ◎ | ◎ | ◎ | ◎ |
| Waiting List | ◎ | ◎ | ◎ | ◎ | ✖ | ✖ |
Table 2: Available Information and actions for each role in the Roles pallet.
Finally, according to the rules described so far, users request and receive their roles, in order to reach the distribution shown in Table 1.
Time to move to the next pallet: Housing Fund.
3) Housing Fund Pallet
In the second step, investors use the Housing Fund pallet to contribute to assets.
| Servicer | Seller | Notary | Representative | Investor | Tenant | |
| Available Fields/Information | ||||||
| account_id | ◎ | ◎ | ◎ | ◎ | ◎ | ◎ |
| age | ◎ | ◎ | ◎ | ◎ | ◎ | ◎ |
| activated | ◎ | ◎ | ◎ | ◎ | ✖ | ✖ |
| verifier | ◎ | ◎ | ◎ | ✖ | ✖ | ✖ |
| assets_accounts | ✖ | ✖ | ✖ | ◎ | ◎ | ◎ |
| rent | ✖ | ✖ | ✖ | ✖ | ✖ | ◎ |
| Available Actions | ||||||
| Contribute to the fund | ✖ | ✖ | ✖ | ✖ | ◎ | ✖ |
| Withdraw from the fund | ✖ | ✖ | ✖ | ✖ | ◎ | ✖ |
Table 3: Available Information and actions for each role in the Housing Fund pallet.
The following conditions apply to fund contribution:
- Minimum contribution of $5000.
- Maximum Contribution of $20,000 (Not in use at the moment).
- Fund Threshold of $100,000 (Not in use at the moment).
All information relative to fund contributions are stored in the Housing Fund pallet, and are available for other pallets to use. For this reason, the Housing Fund pallet, as well as the Roles pallet will be mentioned in the explanation of several other pallets.
4) Onboarding Pallet & NFT Pallet
Onboarding & NFT pallets are tightly coupled pallets and it would be very difficult to explain the contents of one without the other.
Now that we have money in the housing fund, Bob the Seller will create a proposal using the Onboarding Pallet. This pallet is tightly coupled with the NFT pallet, and allows Sellers to fulfill the following tasks:
a) Create an asset sale proposal
Here, through the use of the create_and_submit_proposal the Seller selects between different classes of assets (Houses, Apartment complex, Offices, etc...) provided by the NFT pallet, and defines the price, name, additional information describing the asset (metadata), before creating it. The NFT pallet is then used to create an asset sale proposal that will be transferred to the Voting pallet if submitted by the seller/NFT minter.
Only Sellers have the authority to create an asset.
In the background, an NFT is minted at asset creation by the NFT pallet (in other words the seller has authority on minting a new NFT), using the information provided by the seller. This NFT is also given an ID connected to its asset class. Submitting the asset or not after creation is among the choices offered to the seller, as a modifiable parameter.
b) Modify asset specifications before submission
It is possible to create an asset, without immediately submitting it for a review by the House Council (see the Voting pallet). In this case, the seller might want to modify the asset’s metadata, or add it: the right to set/modify data is also defined in the NFT pallet and is provided to Sellers.
After creation, the asset can be submitted for review to the House Council, before being transferred to Investors for a vote (Voting pallet).
The Onboarding pallet also introduces the concept of asset status (EDITING, REVIEWING, ONBOARDED, FINALIZING, FINALIZED, REJECTED), which describes the position of the asset in the Fair Squares workflow.
| Servicer | Seller | Notary | Representative | Investor | Tenant | |
| Available Fields/Information | ||||||
| account_id | ◎ | ◎ | ◎ | ◎ | ◎ | ◎ |
| age | ◎ | ◎ | ◎ | ◎ | ◎ | ◎ |
| activated | ◎ | ◎ | ◎ | ◎ | ✖ | ✖ |
| verifier | ◎ | ◎ | ◎ | ✖ | ✖ | ✖ |
| assets_accounts | ✖ | ✖ | ✖ | ◎ | ◎ | ◎ |
| rent | ✖ | ✖ | ✖ | ✖ | ✖ | ◎ |
| Available Actions | ||||||
| create_and_submit_proposal | ✖ | ◎ | ✖ | ✖ | ✖ | ✖ |
| submit_awaiting | ✖ | ◎ | ✖ | ✖ | ✖ | ✖ |
| reject_edit | ◎ | ✖ | ✖ | ✖ | ✖ | ✖ |
| reject_destroy | ◎ | ✖ | ✖ | ✖ | ✖ | ✖ |
| change_status | ◎ | ✖ | ✖ | ✖ | ✖ | ✖ |
Table 4: Available Information and actions for Servicer and Seller roles in the Onboarding Pallet.
You can also see in Table 4 that the Onboarding pallet allows a Servicer to reject an asset proposal for editing or destruction, depending on the case at hand. From the NFT pallet side, this means editing the NFT’s metadata, or burning the NFT. Some of the main functions of the NFT pallet are shown in Table 5.
Creation & submission of a proposal is not free of charge for the Seller: a proposal fee, which represents 10% of the asset price (configurable), is reserved at creation of the proposal, and slashed if the proposal is destroyed. If rejected for editing, only 10% of the reserved fees are slashed, and if accepted, remaining reserved fees are returned.
| Servicer | Seller | Notary | Representative | Investor | Tenant | |
| Available Fields/Information | ||||||
| account_id | ◎ | ◎ | ◎ | ◎ | ◎ | ◎ |
| age | ◎ | ◎ | ◎ | ◎ | ◎ | ◎ |
| activated | ◎ | ◎ | ◎ | ◎ | ✖ | ✖ |
| verifier | ◎ | ◎ | ◎ | ✖ | ✖ | ✖ |
| assets_accounts | ✖ | ✖ | ✖ | ◎ | ◎ | ◎ |
| rent | ✖ | ✖ | ✖ | ✖ | ✖ | ◎ |
| Available Actions | ||||||
| create_collection | ◎ | ✖ | ✖ | ✖ | ✖ | ✖ |
| mint | ✖ | ◎ | ✖ | ✖ | ✖ | ✖ |
| transfer* | ◎ | ✖ | ✖ | ✖ | ✖ | ✖ |
| burn | ◎ | ✖ | ✖ | ✖ | ✖ | ✖ |
| destroy_collection | ◎ | ✖ | ✖ | ✖ | ✖ | ✖ |
Table 5: Available Information and actions for Servicer and Seller roles in the in the NFT Pallet.
5) Voting pallet
| Servicer | Seller | Notary | Representative | Investor | Tenant | |
| Available Fields/Information | ||||||
| account_id | ◎ | ◎ | ◎ | ◎ | ◎ | ◎ |
| age | ◎ | ◎ | ◎ | ◎ | ◎ | ◎ |
| activated | ◎ | ◎ | ◎ | ◎ | ✖ | ✖ |
| verifier | ◎ | ◎ | ◎ | ✖ | ✖ | ✖ |
| assets_accounts | ✖ | ✖ | ✖ | ◎ | ◎ | ◎ |
| rent | ✖ | ✖ | ✖ | ✖ | ✖ | ◎ |
| Available Actions | ||||||
| council_vote | ◎ | ✖ | ✖ | ✖ | ✖ | ✖ |
| council_close_vote | ◎ | ✖ | ✖ | ✖ | ✖ | ✖ |
| investor_vote | ✖ | ✖ | ✖ | ✖ | ◎ | ✖ |
Table 6: Available Information and actions for Seller and Investor roles in the Voting pallet.
This is the governance system used to decide if an asset is valid for purchase or not. It is composed of two phases:
The council conducts the first review of an asset proposal created by a Seller, in order to spot any irregularities, and conducts a vote.
Composition of the council still has to be clarified (real estate professional, lawyer, community members, Fair Squares team members, etc.). At this stage, the asset might be rejected for editing if a minor compliance problem is detected, or rejected for destruction, if the asset specifications, or the Seller are in violation of the terms of Fair Squares platform.
If approved by the council, the asset’s proposal is transferred to an Investors' vote session. Investors decide through a vote if they want their Fair Squares fund to invest in this asset, and eventually become one of the co-owners (if selected by the FS algorithm) of this asset.
A summary of the proposal submission workflow is shown in Figure 1 below.
Figure 1 - Proposal submission workflow. This workflow only shows the tasks performed by the NFT, Onboarding, and Voting pallets.
6) Bidding pallet
The Bidding pallet regularly scans the chain, looking for ONBOARDED assets, and executes the following tasks when one is found:
- Check that the Housing Fund has enough funds to purchase the asset.
- Generate a list of investors for the asset.
Generating a list of investors is a core functionality of Fair Squares, and is obeying the following conditions (configurable):
- The maximum asset share per investor is 40%
- The minimum asset share per investor is 5%
Through the use of a First Come First Serve principle, the bidding pallet creates an owners list as described in Table 6 below:
| INVESTORS | Contribution age (in blocks) | Contribution to the fund | INVESTOR Share in the Housing Fund (%) |
|---|---|---|---|
| KillMonger | 55 | $6,000,000.00 | 13.8 |
| Aluman | 54 | $9,000,000.00 | 20.7 |
| Shikamaru | 53 | $3,500,000.00 | 8.0 |
| Geraldo | 52 | $8,000,000.00 | 18.4 |
| Obito | 51 | $5,000,000.00 | 11.5 |
| Hans | 50 | $7,000,000.00 | 16.1 |
| Alice//stash | 49 | $3,000,000.00 | 6.9 |
| Bob//stash | 48 | $2,000,000.00 | 4.6 |
Table 7: shares & contributions.
In this example, we will consider an asset with a price of 10 million US dollars. Table 8 shows a brief recap of the scenario's general configuration :
| USD | % | |
|---|---|---|
| Housing Fund | $43,500,000 | - |
| Asset price | $10,000,000 | 100 |
| Min Asset share | $500,000 | 5 |
| Max Asset share | $4,000,000 | 40 |
Table 8: Scenario's setting.
The following criteria are used to organize investors who will become future owners of an asset:
- Oldest contribution has higher priority
- In order to get a list of eligible investors, temporary shares are attributed as below:
- If the investor’s invested amount in the housing fund is greater than maximum authorized contribution to a purchase, maximum contribution is selected (40% of the purchase price)
- If the investor's invested amount in the housing fund is in the normal range (between 5% & 40% of the purchase price), then the share is calculated as a percentage of the purchase price.
| INVESTORS | contribution Age (in blocks) | Contribution to the fund | Temporary share (%) |
|---|---|---|---|
| KillMonger | 55 | $6,000,000.00 | 40 |
| Aluman | 54 | $9,000,000.00 | 40 |
| Shikamaru | 53 | $3,500,000.00 | 35 |
| Geraldo | 52 | $8,000,000.00 | 40 |
| Obito | 51 | $5,000,000.00 | 40 |
| Hans | 50 | $7,000,000.00 | 40 |
| Alice//stash | 49 | $3,000,000.00 | 30 |
| Bob//stash | 48 | $2,000,000.00 | 20 |
Table 9: Temporary asset share distribution.
The next step explains how the Eligible investors list is used to distribute the asset among the investors. In this new scenario, Mr. A already received his asset share (x0_final). Other members still have temporary shares, and the diagram below explains the process used to determine Mr. B final share (x1_final). Y is the total asset share: 100%.
Figure 2 - Final Asset share calculation process.
The same process is used for Mr. C share calculation. In the case of Mr. C however, instead of (Y-x0_final) in check no. 1, we will use: (Y - x0_final - x1_final), as we want the remaining asset share after distribution to Mr. B when doing the different checks.
7) Finalizer Pallet
Onboarded assets still need to go through a final round of scrutiny before being considered valid for purchase.
Throughout the Finalizer pallet, a Notary receives Onboarded assets information from the Bidding pallet,
and conducts a deeper off-chain legal investigation: the asset's status then changes from Onboarded to Finalising.
Assets accepted by the Notary receive the status Finalised, while others are Rejected.
| Servicer | Seller | Notary | Representative | Investor | Tenant | |
| Available Fields/Information | ||||||
| account_id | ◎ | ◎ | ◎ | ◎ | ◎ | ◎ |
| age | ◎ | ◎ | ◎ | ◎ | ◎ | ◎ |
| activated | ◎ | ◎ | ◎ | ◎ | ✖ | ✖ |
| verifier | ◎ | ◎ | ◎ | ✖ | ✖ | ✖ |
| Available Actions | ||||||
| validate_transaction_asset | ✖ | ✖ | ◎ | ✖ | ✖ | ✖ |
| reject_transaction_asset | ✖ | ✖ | ◎ | ✖ | ✖ | ✖ |
| cancel_transaction_asset | ✖ | ◎ | ✖ | ✖ | ✖ | ✖ |
Table 10: Available Information and actions for Notary and Seller roles in the Finaliser Pallet.
8) Share Distributor pallet
Once an asset has the status Finalised, the Bidding pallet will first use the Share Distributor pallet to create a virtual account connected to the new owners. This virtual will store the NFT created earlier during asset submission by the seller. Once it is confirmed that the Nft corresponding to this asset, was transfered from the Seller to the virtual account/asset owners, the seller account finally receives the payment due for the asset purchase.
Figure 2 - Share Distributor flow part.1: Creation of a virtual account to store the asset NFT
In the second task of the Share_Distributor pallet, the virtual account mints 1000 ownership tokens specific to the asset. These tokens will be distributed to the owners according to their contribution to the asset purchase: a 20% contribution will receive 200 ownership tokens. The possession of ownership tokens, together with the informations contained in the Nft, stored in the virtual account, are what define the fractional ownership of the asset by an individual in the Fair Squares ecosystem.
Figure 2 - Share Distributor flow part.2: Minting and distribution of Ownership tokens by the virtual account.
Up until this point the purpose of the workflow was to purchase an asset. With the Asset Management & Tenancy pallets, we are entering the second part of the workflow, revolving around the purchased asset management.
9) Tenancy pallet
There are no string attached after receiving the Tenant role in the Role Pallet. However, in order to become an active Tenant, the Tenancy Pallet must be used.
- First and foremost, the Tenancy Pallet allows a prospecting Tenant to request a purchased asset. For this purpose, the future Tenant will have to register more informations about himself, and become a prospecting/registered Tenant. The asset request notifies the corresponding Representative, who, after evaluation of the Tenant profile, will provide his/her judgement to the asset Owners, and start a referendum for them to take the final decision.
- Once accepted by a group of owner, the prospecting Tenant can pay the guaranty deposit of the asset, and seal the deal. this action connects him to the asset requested.
- Finally, the Tenancy Pallet allows the Tenant to pay his monthly rent at any moment. The length of the lease contract being 1 year, the Tenant won't be able to do more than 12 payments.
| Servicer | Seller | Notary | Representative | Investor | Tenant | |
| Available Fields/Information | ||||||
| account_id | ◎ | ◎ | ◎ | ◎ | ◎ | ◎ |
| rent | ✖ | ✖ | ✖ | ✖ | ✖ | ◎ |
| age | ◎ | ◎ | ◎ | ◎ | ◎ | ◎ |
| asset_account | ✖ | ✖ | ✖ | ◎ | ◎ | ◎ |
| contract_start | ✖ | ✖ | ✖ | ✖ | ✖ | ◎ |
| remaining_rent | ✖ | ✖ | ✖ | ✖ | ✖ | ◎ |
| remaining_payment | ✖ | ✖ | ✖ | ✖ | ✖ | ◎ |
| registered | ✖ | ✖ | ✖ | ✖ | ✖ | ◎ |
| Available Actions | ||||||
| request_asset | ✖ | ✖ | ✖ | ✖ | ✖ | ◎ |
| pay_guaranty_deposit | ✖ | ✖ | ✖ | ✖ | ✖ | ◎ |
| pay_rent | ✖ | ✖ | ✖ | ✖ | ✖ | ◎ |
Table 11: Available Information and actions for Tenant role in the Tenancy Pallet.
10) Asset Management pallet
The implemented workflow in this pallet is as follows:
| Servicer | Seller | Notary | Representative | Investor | Tenant | |
| Available Fields/Information | ||||||
| account_id | ✖ | ✖ | ✖ | ◎ | ◎ | ✖ |
| activated | ✖ | ✖ | ✖ | ◎ | ✖ | ✖ |
| age | ◎ | ◎ | ◎ | ◎ | ◎ | ◎ |
| asset_account | ✖ | ✖ | ✖ | ◎ | ✖ | ◎ |
| index | ✖ | ✖ | ✖ | ✖ | ✖ | ◎ |
| share | ✖ | ✖ | ✖ | ✖ | ◎ | ✖ |
| selections | ✖ | ✖ | ✖ | ✖ | ◎ | ✖ |
| registered | ✖ | ✖ | ✖ | ✖ | ✖ | ◎ |
| Available Actions | ||||||
| launch_representative_session | ✖ | ✖ | ✖ | ✖ | ◎ | ✖ |
| owners_vote | ✖ | ✖ | ✖ | ✖ | ◎ | ✖ |
| launch_tenant_session | ✖ | ✖ | ✖ | ◎ | ✖ | ✖ |
Table 12: Available Information and actions for Representative and Investor roles in the Asset_Management Pallet.
Election of a Representative by the new owners
An aspirant Representative can request the role through the Roles Pallet, and is added to a waiting list. Using the Asset_Management Pallet, any owner of any asset can consult the list, and open a referendum for his/her group of owners, in order to elect a Representative. An elected Representative is connected to the corresponding asset of the owner's group. Note that one Representative can be connected to several assets.
Tenant Selection by Representative & owners
Once a Representative is connected to an asset, a prospective Tenant can send a request for this Asset (see Tenancy Pallet). The Representative will then evaluate the Tenant request, and submit the result of the evaluation together with the Tenant information to the Owners, while at the same time, opening a referendum for the Owners to vote on this proposal.
Guaranty Deposit payment
If accepted by the Owners after a referendum, the Tenant receives a Guaranty Deposit payment request, sent by the Owners asset's account. Paying the guaranty deposit will seal the agreement, and connect the Tenant to the requested asset.
Periodic actions
Additionally, the Asset_Management Pallet will periodically check the payment status of active Tenants, and notify them if they are in debts. If a rent has been payed, It will distribute the rent to the Owners, after reserving a small percentage for future asset maintenance expenses.