# Hemergy contracts

The following sections constitue a mere translation of the contracts' native specifications into a human-friendlier documentation. As for any handwritten documentation (it seems every NatSpec-to-HTML translators libraries are deprecated), bear in mind the following might not perfectly reflect the contracts' code as time and commits pass.

## Factory.sol

### Reason of being

The factory contract is the originator of the beneficiaries, investors and project-specific escrow and ERC20 contracts. While there is a single instance of the beneficiaries and investors contracts per factory instance, there can be thousands of escrow and ERC20 contracts instances. Anybody can instanciate these latter contracts through a public entrypoint. The contract's storage keeps track of the factory-instanciated - understand legit - escrow's and ERC20's public addresses, to ensure no one can bypass it to instanciate new counterfeit escrow/ERC2 contracts.

### Entrypoints

#### createNewEscrow

Creates a new escrow contract instance along with its associated token.

|Parameters | Description |
|:----------|:------------|
|lockDuration | The delay, expressed in seconds, during which funds cannot be withdrawn from the contract. |
|maxInvestors | The maximum number of investors. |
|entryTicket | The minimum value a user can send to the contract. |
|midCap | The minimum contract's balance needed to lock funds. |
|maxEquity | The maximum mid cap percentage a user can send to the contract. |

|Return | Description |
|:----------|:------------|
|t | A tuple comprising the public addresses of the escrow and token contracts instances. |

#### changeTokenParameters

Changes escrow-specific tokens optional parameters.

|Parameters | Description |
|:----------|:------------|
| \_initialAmount | The total token supply. |
| \_tokenName | The token's name. |
| \_decimalUnits | The token's number of decimals. |
| \_tokenSymbol | The token's symbol. |

#### getInvestorsListAddress (view)

Gets the genuine investors list contract address. The investors list contract is created along with the factory contract.

|Return | Description |
|:----------|:------------|
| investorsContractAddress | The investors list contract address. |

#### getBeneficiariesListAddress (view)

Gets the factory-instantiated beneficiaries list contract address. The investors list contract is created along with the factory contract.

|Return | Description |
|:----------|:------------|
|beneficiariesContractAddress | The investors list contract address. |

#### checkIfContractIsEscrow (view)

Tells whether an input contract is an authentic escrow contract.

|Parameters | Description |
|:----------|:------------|
|escrowContractAddress | The address of the deployed escrow contract. |

|Return | Description |
|:----------|:------------|
| isEscrow | A boolean stating whether or not the input address is a known escrow contract. |

#### checkIfContractIsToken (view)

Checks whether a deployed contract is an authentic escrow-specific token contract.

|Parameters | Description |
|:----------|:------------|
| token | The token contract address to be tested. |

|Return | Description |
|:----------|:------------|
| isToken | A boolean stating whether the input address is a known token contract. |

### Events

#### InvestorsContractCreated

Emitted whenever a new investors list is instantiated.

|Parameters | Description |
|:----------|:------------|
| investorsContractAddress | The investors contract address. |

#### BeneficiariesContractCreated

Emitted whenever a new investors list is instantiated.

|Parameters | Description |
|:----------|:------------|
| beneficiariesContractAddress | The investors contract address. |

#### EscrowContractCreated

Emitted whenever a new escrow contract is instantiated.

|Parameters | Description |
|:----------|:------------|
| escrow | The escrow contract address. |
|token | The escrow-specific token contract address. |

### Errors

#### UserIsNotAdmin

The message sender needs to have admin rights to perform this action.

## Beneficiaries.sol

### Reason of being

This contract keeps track of the approved projects' beneficiaries - the public addresses which are allowed to receive funds by the end of a fundraising process.

### Entrypoints

#### approveBeneficiary

Marks the provided public address as approved. The provided public address cannot be marked as approved beforehand.

|Parameters | Description |
|:----------|:------------|
| beneficiary | The public address to approve. |

#### revokeBeneficiary

Marks the provided public address as unapproved. The provided public address cannot be unmarked if it was not approved in the first place.

|Parameters | Description |
|:----------|:------------|
| beneficiary | The public address to revoke. |

#### isApproved (view)

Returns whether the provided public address is marked as approved.

|Parameters | Description |
|:----------|:------------|
| beneficiary | The public address to assess. |

|Return | Description |
|:----------|:------------|
|approved | A boolean that evaluates to true when the public address is approved. |

### Errors

#### ContractIsNotBeneficiariesList (contract-related error)

This escrow contract does not belong to the whitelisted beneficiaries contracts list.

#### SenderIsNotAdmin (entrypoint error)

No one but the contract's administrator can perform this action.

#### BeneficiaryIsAlreadyApproved (entrypoint error)

The provided beneficiary has already been approved by the contract's admin.

#### BeneficiaryNeedsToBeApproved (entrypoint error)

The provided beneficiary needs to be approved in order to be revoked.

## Investors.sol

### Reason of being

This contract keeps track of the approved projects' investors - the public addresses which are allowed to invest in a project.

### Entrypoints

#### approveInvestor

Marks the provided public address as approved. The provided public address cannot be marked as approved beforehand.

|Parameters | Description |
|:----------|:------------|
| investor | The public address to approve. |

#### revokeInvestor

Marks the provided public address as unapproved. The provided public address cannot be unmarked if it was not approved in the first place.

|Parameters | Description |
|:----------|:------------|
| investor | The public address to revoke. |

#### isApproved (view)

Returns whether or not the provided public address is marked as approved.

|Parameters | Description |
|:----------|:------------|
| investor | The public address to assess. |

|Return | Description |
|:----------|:------------|
| approved | A boolean that evaluates to true when the public address is approved. |

### Errors

#### ContractIsNotInvestorsList (contract-related error)

This escrow contract does not belong to the whitelisted investors contracts list.

#### SenderIsNotAdmin (entrypoint error)

No one but the contract's administrator can perform this action.

#### InvestorIsAlreadyApproved (entrypoint error)

The provided investor has already been approved by the contract's admin.

#### InvestorNeedsToBeApproved (entrypoint error)

The provided investor needs to be approved in order to be revoked.

## Escrow.sol

### Reason of being

This contract keeps track of the state of a specific fundraising process and stores the investors' funds.

### Entrypoints

#### addBeneficiary

Marks a public address as a project's beneficiary along with its share.

|Parameters | Description |
|:----------|:------------|
| beneficiary | A public address which will be sent an ethers share by the end of the fundraising. |
| share | An integer comprised between 0 and 100 that describes the proportion of funds the beneficiary will receive by the end of the fundraising. |
| payments | The total number of payments. |
| timeBetweenPayments | The seconds between each payment, if payments > 1. |

#### revokeBeneficiary

Unmarks a public address as a project's beneficiary.

|Parameters | Description |
|:----------|:------------|
| beneficiary | The supposedly contract-stored public address to revoke. |

#### modifyBeneficiaryShare

Modifies a beneficiary's share.

|Parameters | Description |
|:----------|:------------|
| beneficiary | The involved beneficiary's public address. |
| newShare | The new share to associate to this public address. |

#### invest

Sends ethers to the escrow contract. This entrypoint needs to be called with a non-zero message value expressed in gwei.

#### withdraw

Sends back a specific amount of ethers to the message sender.

|Parameters | Description |
|:----------|:------------|
| amount | The ethers amount to withdraw from the contract. |

#### vote

Vote to say whether or not raised funds should go to the beneficiaries. Each vote is weighed according to the voter's total investment.

|Parameters | Description |
|:----------|:------------|
| choice | The vote's value. |

#### claimRefund

Sends back to the message sender his/her original investment.

#### claimShare

Sends ethers to the message sending beneficiary.

#### claimEquities

Sends escrow-specific tokens to the message sender.

#### sendEquities

Sends escrow-specific tokens to another whitelisted investor on behalf of `msg.sender`.

|Parameters | Description |
|:----------|:------------|
| recipient | A public address to send equities to. |
| equitiesToSend | The amount of equities to send to recipient. |

#### isAuthenticEscrow (view)

Returns true when this contract belongs to the factory's whitelist.

|Return | Description |
|:----------|:------------|
| isEscrow | A boolean stating whether this contract address belongs to the whitelist. |

#### isAuthenticToken (view)

Returns true when this contract belongs to the factory's whitelist.

|Return | Description |
|:----------|:------------|
| isToken | A boolean stating whether this contract address belongs to the whitelist. |

#### getTokenAddress (view)

Returns this escrow-specific token contract address.

|Return | Description |
|:----------|:------------|
| address | The token's contract address. |

#### getTotalInvestedAmount (view)

Returns the ethers amount investors sent to the contract.

|Return | Description |
|:----------|:------------|
| amount | The total invested ethers amount. |

#### getFundraiserAddress (view)

Returns the public address of the project's originator.
|Return | Description |
|:----------|:------------|
| address | The fundraiser's address. |

#### getEntryTicketValue (view)

Returns the minimum ethers value an investor can send to the contract.

|Return | Description |
|:----------|:------------|
|entryTicket | The value, expressed in Gwei, of the entry ticket. |

#### getMidCapValue (view)

Returns the fundraising financial objective.

|Return | Description |
|:----------|:------------|
|midCap | The value, expressed in Gwei, of the middle cap. |

#### getMaxEquity (view)

Returns the maximum equities an investor can get by the end of the fundraising process.

|Return | Description |
|:----------|:------------|
|maxEquity | An integer comprised within 1 and 49. |

#### getEquitiesLeft (view)

Returns the equities that are left to be shared.

|Return | Description |
|:----------|:------------|
|equitiesLeft | An integer, comprised within 0 and 100. |

#### getMaxInvestorsValue (view)

Returns the maximum number of authorized investors for this project.

|Return | Description |
|:----------|:------------|
|maxInvestors | an integer comprised within 1 and 255. |

#### getInvestorsCounterValue (view)

Returns the current number of users who invested in this project.

|Return | Description |
|:----------|:------------|
|investorsCounter | An integer comprised within 0 and maxInvestors. |

#### getCreditStatus (view)

Returns the current state of the credit's approval status.

|Return | Description |
|:----------|:------------|
| creditStatus | A string which value can either be "Unrequested", "Pending", "Granted" or "Rejected". |

#### getLeftToBeShared (view)

Returns the percentage of the raised funds that are left to be shared between the project's beneficiaries.

|Return | Description |
|:----------|:------------|
| leftToBeShared | An integer comprised within 0 and 100. |

#### getInvestorInvestedAmount (view)

Returns the invested amount of a given investor in this project.

|Parameters | Description |
|:----------|:------------|
| investor | The public address of the queried investor. |

|Return | Description |
|:----------|:------------|
|investedAmount | The value, expressed in Gwei, of the invested amount. |

#### getInvestorEquities (view)

Returns a specific investor's equities in the fundraised project.

|Parameters | Description |
|:----------|:------------|
| investor | The public address of the investor. |

|Return | Description |
|:----------|:------------|
| equities | The investor's equities. |

#### getInvestorVoteChoice (view)

Returns the vote choice of a given investor stating whether or not the fundraising should succeed.

|Parameters | Description |
|:----------|:------------|
| investor | The public address of the queried investor. |

|Return | Description |
|:----------|:------------|
| choice | The investor's vote choice, a string which can either be "Go" or "Nogo". |

#### getBeneficiaryShare (view)

Returns the share of a given beneficiary ie the percentage of the middle cap that will be sent by the end of the fundraising.

|Parameters | Description |
|:----------|:------------|
| beneficiary | The public address of the queried beneficiary. |

|Return | Description |
|:----------|:------------|
| share | An integer, comprised within 0 and 100. |

#### getPaymentsLeft (view)

Returns the number of payments left of a specific beneficiary.

|Parameters | Description |
|:----------|:------------|
| beneficiary | The public address of the queried beneficiary. |

|Return | Description |
|:----------|:------------|
| paymentsLeft | An integer comprised within 0 and totalPayments. |

#### getNumberOfPayments (view)

Returns the number of payments planned for a specific beneficiary.

|Parameters | Description |
|:----------|:------------|
| beneficiary | The beneficiary's public address. |

|Return | Description |
|:----------|:------------|
| payments | An integer comprised within 1 and 255. |

#### getTimeBetweenPayments (view)

Returns the time between two payments planned for a specific beneficiary.

|Parameters | Description |
|:----------|:------------|
| beneficiary | The beneficiary's public address. |

|Return | Description |
|:----------|:------------|
| timeBetweenPayments | A period expressed in seconds. |

#### getLockTimestamp (view)

Returns the timestamp of the time when funds have been locked in the contract.

|Return | Description |
|:----------|:------------|
| lockedTimestamp | An integer. |

#### getLockDuration (view)

Returns the maximum number of seconds funds will remain locked in the contract.

|Return | Description |
|:----------|:------------|
|lockDuration | An integer. |

#### getTimeLeft (view)

Returns the time that is left before voting is over and ballots are counted.

|Return | Description |
|:----------|:------------|
| timeLeft | The time left in seconds. |

#### getGoCounterValue (view)

Returns the number of votes advocating for funds being released in favor of beneficiaries.

|Return | Description |
|:----------|:------------|
| goCounterValue | The number of votes. |

#### getNogoCounterValue

Returns the number of votes advocating for funds being released in favor of investors.

|Return | Description |
|:----------|:------------|
| nogoCounterValue | The number of votes. |

### Events

#### FundsLocked

Emitted whenever funds are locked in the escrow contract.

#### LockDurationExtended

Emitted whenever the funds lock duration is extended.

|Parameters | Description |
|:----------|:------------|
| newLockDuration | The newly stored lock duration. |

#### BeneficiaryAdded

Emitted whenever a new beneficiary has been added by the fundraiser.

|Parameters | Description |
|:----------|:------------|
|newBeneficiary | The public address that has been added to the beneficiaries list. |

#### BeneficiaryRevoked

Emitted whenever a beneficiary has been revoked by the fundraiser.

|Parameters | Description |
|:----------|:------------|
|beneficiary | The public address that has been removed from the beneficiaries list. |

#### ShareUpdated

Emitted whenever a beneficiary's share has been updated by the fundraiser.

|Parameters | Description |
|:----------|:------------|
| beneficiary | The public address of the involved beneficiary. |
| newShare | The new share of `beneficiary`. |

#### Invested

Emitted whenever an investor has sent funds to the contract through the invest entrypoint.

|Parameters | Description |
|:----------|:------------|
| investor | The public address of `msg.sender`. |
| amount | The `msg.value` coming with the entrypoint's call. |

#### Withdrawn

Emitted whenever an investor has withdrawn funds from the contract.
|Parameters | Description |
|:----------|:------------|
| investor | The public address of `msg.sender`. |
| amount | The quantity of Gwei the user withdraws from the contract. |

#### Voted

Emitted whenever an investor has voted in favor of the fundraising success or failure.

|Parameters | Description |
|:----------|:------------|
| investor | The public address of `msg.sender`. |
| choice | The choice of said investor, a value which can either be "Go" or "Nogo". |

#### RefundClaimed

Emitted whenever an investor claims a refund by the end of the fundraising (if unsuccessful).

|Parameters | Description |
|:----------|:------------|
| investor | The public address of `msg.sender`. |

#### EquitiesClaimed

Emitted whenever an investor claims his/her equities by the end of the fundraising (if successful).

|Parameters | Description |
|:----------|:------------|
| investor | The public address of `msg.sender`. |

#### EquitiesSent

Emitted whenever an investor send part of his/her equities to another approved investor.

|Parameters | Description |
|:----------|:------------|
| investor | The public address of `msg.sender`. |
| recipient | The public address of the equities recipient. |
| equitiesToSend | The quantity of equities to send. |

#### ShareClaimed

Emitted whenever a beneficiary claims his/her share.

|Parameters | Description |
|:----------|:------------|
| beneficiary | The public address of `msg.sender`. |

### Errors

#### ContractIsNotEscrow (contract error)

This escrow contract does not belong to the whitelisted escrow contracts list.

#### ContractIsNotToken (contract error)

This token contract does not belong to the whitelisted escrow-specific token contracts list.

#### InvalidEntryTicket (constructor error)

The provided entry ticket value either equals to zero or is higher than the max possible equity.

#### LockDurationEqualsToZero (constructor error)

Lock duration needs to be higher than zero.

#### MaxInvestorsEqualsToZero (constructor error)

The maximum number of investors needs to be higher than zero.

#### MaxInvestorsIsTooHigh (constructor error)

The maximum number of investors needs to be lower than 150.

#### MaxEquityEqualsToZero (constructor error)

The max equity investors can get needs to be higher than zero.

#### MaxEquityIsTooHigh (constructor error)

The max equity investors can get needs to be lower than 50.

#### NoFactory (constructor error)

Factory is not referenced in the contract.

#### InvalidCreditStatus (credit error)

The credit status is not set to the expected value.

#### SenderIsNotTheFundraiser (fundraiser-side error)

Only the fundraiser can perform this action.

#### InvalidLockDuration (fundraiser-side error)

The provided new lock duration is either lower or more than twice as big as the current.

#### VotesAreOpen (fundraiser-side error)

Lock duration cannot be extended since the voting period started.

#### VotesAreClosed (fundraiser-side error)

This action cannot be performed since votes are closed.

#### SenderIsNotAWhitelistedInvestor (investor-side error)

Only a whitelisted investor can perform this action.

#### SenderIsNotAProjectInvestor (investor-side error)

Only a whitelisted investor who actually invested in the project can perform this action.

#### NotEnoughBeneficiariesYet (investor-side error)

The fundraising cannot start before shares have been totally set between beneficiaries.

#### InvestmentSurpassesMaxEquity (investor-side error)

The amount sent to the contract surpasses the maximum equity an investor can get.

#### InvestmentSurpassesEquitiesLeft (investor-side error)

The amount sent to the contract surpasses the equities left to be shared between investors.

#### InvestmentIsLowerThanEntryTicket (investor-side error)

The amount sent to the contract is lower than the minimum authorized investment.

#### TransferFailed (investor-side error)

The ethers transfer failed.

#### ValueIsNotAnInteger (investor-side error)

The amount sent to the contract is not an integer.

#### GreaterThanInvestment (investor-side error)

The requested amount to withdraw is greater than the investor's original investment.

#### NoInvestors (investor-side error)

This action can be performed as long as there are project investors.

#### TooEarlyToClaimRefund (investor-side error)

This action cannot be performed yet.

#### AmountIsGreaterThanInvestorsEquities (investor-side error)

Amount to send is greater than investor's equities.

#### InvestorsEquitiesExceedsLimit (investor-side error)

Sending this amount of equities, the recipient would exceed the max allowed equities per investor.

#### TooEarlyToVote (vote-related error)

The fundraiser has not opened votes yet.

#### InvestorAlreadyVoted (vote-related error)

The investor has already voted.

#### TooLateToVote (vote-related error)

Investors cannot vote once the lock duration has expired.

#### InvalidVoteChoice (vote-related error)

Submitted vote cannot be counted.

#### TooBigOfAShare (beneficiary-side error)

A beneficiary cannot be attributed more than what is left to be shared.

#### BeneficiaryAlreadyHasAShare (beneficiary-side error)

The provided beneficiary already has a share.

#### ShareEqualsToZero (beneficiary-side error)

The beneficiary's share needs to be greater than zero.

#### InvalidNumberOfPayments (beneficiary-side error)

The provided number of payments either equals to zero or surpasses 2^8.

#### InvalidTimeBetweenPayments (beneficiary-side error)

Time between payments cannot equal to zero except in the case of a single payment.

#### NotAWhitelistedBeneficiary (beneficiary-side error)

The provided address does not belong to any whitelisted beneficiaries.

#### NotAProjectBeneficiary (beneficiary-side error)

The provided address does not belong to any mentionned project's beneficiaries.

#### AlreadyPaid (beneficiary-side error)

This beneficiary has already been paid.

#### TooEarlyToClaimShare (beneficiary-side error)

This beneficiary's time between payments has not passed.

## ERC20.sol

### Reason of being

This contract defines the shape of the tokenized shares investors receive by the end of a successful fundraising process.

### Entrypoints

#### balanceOf (view)

|Parameters | Description |
|:----------|:------------|
| \_owner | The address from which the balance will be retrieved. |

|Return | Description |
|:----------|:------------|
| balance | The balance. |

#### transfer

Sends `_value` token to `_to` from `msg.sender`.

|Parameters | Description |
|:----------|:------------|
| \_to | The address of the recipient |
| \_value | The amount of token to be transferred. |

|Return | Description |
|:----------|:------------|
|success | Whether the transfer was successful or not. |

#### transferFrom

Sends `_value` token to `_to` from `_from` on the condition it is approved by `_from`.

|Parameters | Description |
|:----------|:------------|
| \_from | The address of the sender. |
| \_to | The address of the recipient. |
| \_value | The amount of token to be transferred. |

|Return | Description |
|:----------|:------------|
| success | Whether the transfer was successful or not. |

#### approve

`msg.sender` approves `_addr` to spend `_value` tokens.

|Parameters | Description |
|:----------|:------------|
| \_spender | The address of the account able to transfer the tokens. |
| \_value | The amount of wei to be approved for transfer. |

|Return | Description |
|:----------|:------------|
| success | Whether the approval was successful or not. |

#### Allowance (view)

|Parameters | Description |
|:----------|:------------|
| \_owner | The address of the account owning tokens. |
| \_spender | The address of the account able to transfer the tokens. |

|Return | Description |
|:----------|:------------|
| remaining | Amount of remaining tokens allowed to spent. |

### Errors

#### NotOwner

`msg.sender` is not the token contract's owner.

#### NotAllowed

`msg.sender` has not been approved by the contract factory and thus cannot perform this action.

#### SenderIsNotAWhitelistedInvestor

`msg.sender` does not belong to the whitelisted investors list.

#### RecipientIsNotAWhitelistedInvestor

The recipient address does not belong to the whitelisted investors list.