# Revenue Distribution Contract
### Introduction
Blocksquare enables anyone with an internet connection to invest in individual real estate assets through purchase of [BSPT tokens](/infrastructure/tokenization-protocol/bspt-tokens.md). Some real estate assets generate revenues due to rental agreements between the property owner and tenant(s) of the property.
Through the tokenization process, the owner agrees to transfers economic rights onto BSPT token holders, which is achieved with the signing of a [Corporate resolution](/infrastructure/tokenization-protocol/corporate-resolution.md) in which the percentage of revenues is specified. These recurring revenues are to be converted into a stablecoind (e.g. DAI, USDC, USDT) and distributed to BSPT token holders on a predefined time interval (e.g. monthly, quarterly or annually) based on the amount of tokens issued, where 100,000 BSPT represents 100% of the economic rights of the property.
As BSPT tokens can also be traded on the secondary market, there is a certain complexity when it comes to calculating how much of the total revenues should be distributed to each individual BSPT token holder for a given time period. To accurately execute this an off-chain algorithm has been developed by Blocksquare that is then used to place deposits into the Revenue Distribution smart contract deployed on Ethereum mainnet.
The smart contract key functions are listed below.
### Key Events
| Event | Description |
|---|
RevenueAdded(address indexed property, address[] users, uint256[] amounts, uint256 fromTime, uint256 toTime) | An event emitted whenever new revenue is added. |
RevenueClaimed(address indexed property, address indexed user, uint256 amount, uint256 time) | An event emitted whenever a user is claiming revenue |
### Add Revenue
Used to add revenue for a specific property and distribute it among users. Only the system administrator or authorized certified partner can call this function.
**Revenue Distribution**
function addRevenue(address property, address[] memory users, uint256[] memory amount, uint256 from, uint256 to)
* `property`: The address of the property
* `users`: An array of user addresses that we want to add revenue for
* `amount`: An array of amounts that we want to add for the users
* `from`: Start date for revenue calculation
* `to`: End date for revenue calculation
* `RETURN`: No return, reverts on error.
**Solidity**
```solidity
RevenueDistribution revenue = RevenueDistribution(0x123...); // contract address
revenue.addRevenue(property, users, amounts, from, to);
```
**Web3 1.2.6**
```solidity
const property = '0xABC...' // Property 0xABC
const users = ['0x123...'] // User 0x123...
const amounts = [1000 * e6] // 1.000 USDT for example
const fromTime = 1707977495 // 15th February 2024 - 6:11 AM
const toTime = 1708063895 // 16th February 2024 - 6:11 AM
const tx = revenue.methods
.addRevenue(property, users, amount, fromTime, toTime)
.send({ from: sender });
```
### Claim Revenue For Single Property
Used to claim the pending revenue for a single wallet and property. This function doesn't restrict the caller, so you can claim revenue on behalf of other users and send it to their wallet.
**Revenue Distribution**
```solidity
function claimRevenuesForWalletForProperty(address wallet, address property)
```
* `wallet`: Wallet address that has outstanding revenue and that should receive it
* `property`: Property address for which you want to claim revenue
* `RETURN`: No return, reverts on error.
**Solidity**
```solidity
RevenueDistribution revenue = RevenueDistribution(0x123...); // contract address
revenue.claimRevenuesForWalletForProperty(wallet, property);
```
**Web3 1.2.6**
```solidity
const wallet = '0x123...' // Address of the user wallet
const property = '0xABC...'; // Address of the property
const tx = revenue.methods
.claimRevenuesForWalletForProperty(wallet, property)
.send({ from: sender });
```
### Claim Revenue For Multiple Properties
Used to claim the pending revenue for a single wallet and multiple properties. This function doesn't restrict the caller, so you can claim revenue on behalf of other users and send it to their wallet.
**Revenue Distribution**
```solidity
function claimRevenuesForWalletForMultipleProperties(address wallet, address[] memory properties)
```
* `wallet`: Wallet address that has outstanding revenue and that should receive it
* `properties`: Array of property addresses for which you want to claim revenue
* `RETURN`: No return, reverts on error.
**Solidity**
```solidity
RevenueDistribution revenue = RevenueDistribution(0x123...); // contract address
revenue.claimRevenuesForWalletForMultipleProperties(wallet, properties);
```
**Web3 1.2.6**
```solidity
const wallet = '0x123...' // Address of the user wallet
const properties = ['0xABC...', '0xBCD'] // Addresses of the properties
const tx = revenue.methods
.claimRevenuesForWalletForMultipleProperties(wallet, properties)
.send({ from: sender });
```
### Push Revenue To User
Used to claim the pending revenue for a single property and multiple wallets. This function doesn't restrict the caller, so you can claim revenue on behalf of other users and send it to their wallet.
**Revenue Distribution**
function pushRevenueToUser(address property, address[] memory wallets)
* `property`: Property address that has outstanding revenue
* `wallets`: Array of wallet addresses for which you want to claim revenue
* `RETURN`: No return, reverts on error.
**Solidity**
```solidity
RevenueDistribution revenue = RevenueDistribution(0x123...); // contract address
revenue.pushRevenueToUser(property, wallets);
```
**Web3 1.2.6**
```solidity
const property = '0xABC...' // Address of the property
const wallets = ['0x123...', '0x234'] // Addresses of the wallets
const tx = revenue.methods
.claimRevenuesForWalletForMultipleProperties(property, wallets)
.send({ from: sender });
```
### Pending Revenue
Used to check the amount of pending revenue for a specific property and user.
**Revenue Distribution**
```solidity
function pendingRevenue(address property, address user) returns (uint256)
```
* `property`: Property address that has outstanding revenue
* `user`: User address for which you want to check outstanding revenue
* `RETURN`: The amount of outstanding revenue (integer)
**Solidity**
```solidity
RevenueDistribution revenue = RevenueDistribution(0x123...); // contract address
revenue.pendingRevenue(property, user);
```
**Web3 1.2.6**
```solidity
const property = '0xABC...' // Address of the property
const user = '0x123...' // Address of the user wallet
const amount = await revenue.methods.pendingRevenue(property, user).call();
```
### Total Pending Revenue
Used to check the total outstanding revenue for a specific user.
**Revenue Distribution**
```solidity
function totalPendingRevenue(address user) returns (uint256)
```
* `user`: User address for which you want to check the total outstanding revenue
* `RETURN`: The amount of outstanding revenue (integer)
**Solidity**
```solidity
RevenueDistribution revenue = RevenueDistribution(0x123...); // contract address
revenue.totalPendingRevenue(user);
```
**Web3 1.2.6**
```solidity
const user = '0x123...' // Address of the user wallet
const amount = await revenue.methods.totalPendingRevenue(user).call();
```
### Average Monthly Payout
Used to check the average monthly payout for a specific property.
**Revenue Distribution**
```solidity
function getAverageMonthlyPayout(address property) returns (uint256)
```
* `property`: Address of the property we want to check the average monthly payout for
* `RETURN`: The amount of average monthly payout (integer)
**Solidity**
```solidity
RevenueDistribution revenue = RevenueDistribution(0x123...); // contract address
revenue.getAverageMonthlyPayout(property);
```
**Web3 1.2.6**
```solidity
const property = '0xABC...' // Address of the user wallet
const monthlyPayout = await revenue.methods.getAverageMonthlyPayout(property).call();
```
### Total Payout
Used to check the amount of total payouts for a specific property.
**Revenue Distribution**
```solidity
function totalPayout(address property) returns (uint256)
```
* `property`: Address of the property we want to check the total payout for
* `RETURN`: The amount of total payout (integer)
**Solidity**
```solidity
RevenueDistribution revenue = RevenueDistribution(0x123...); // contract address
revenue.totalPayout(property);
```
**Web3 1.2.6**
```solidity
const property = '0xABC...' // Address of the user wallet
const totalPayout = await revenue.methods.totalPayout(property).call();
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.blocksquare.io/for-developers/revenue-distribution-contract.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.