This project implements a Crowdsale contract that facilitates the sale of tokens in exchange for Ether (ETH). The Crowdsale contract allows users to participate in the token sale by sending Ether to the contract address and receiving tokens in return. The project aims to provide a secure and transparent platform for fundraising through token sales.
The Crowdsale contract is the core component of the project and handles the token sale process. It includes features such as:
- Whitelisting: The contract maintains a whitelist of approved addresses that are allowed to participate in the token sale.
- Purchase Restrictions: Minimum and maximum purchase limits are enforced to ensure fairness and prevent abuse.
- Timed Sale: The token sale is conducted within a specific timeframe, allowing participants to buy tokens only during the specified period.
- Refunds: If enabled by the contract owner, participants can request refunds for their purchased tokens after the token sale ends.
- Finalization: At the end of the token sale, the contract owner can finalize the sale and transfer the remaining tokens and Ether to their respective destinations.
To use the Crowdsale contract, follow these steps:
- Clone the repository:
git clone https://github.com/your-username/crowdsale-project.git
- Install dependencies:
npm install
- Configure the contract parameters, such as token price, maximum tokens, sale start and end time, etc., in the contract constructor.
- Deploy the contract to the Ethereum network using Hardhat
- Interact with the contract by sending Ether to the contract address during the token sale period or using other available functions.
To participate in the token sale, users should follow the instructions below:
- Ensure your address is whitelisted by the contract owner. If not, request whitelisting by calling the
requestWhitelist()
function. - Send Ether to the contract address. The amount of Ether sent determines the number of tokens purchased.
- If the token sale is still open and your address is whitelisted, the contract will transfer the corresponding number of tokens to your address.
In this scenario, the token sale campaign is successful. Here's a step-by-step walkthrough of the process:
- The contract owner deploys the Crowdsale contract with the desired parameters, such as token price, maximum tokens, sale start and end time, and purchase restrictions. For this demo purposes, we can set the targeted amount of token sold has reached 80% from the total supply to make sure the campaign is successful.
- The contract owner approves whitelisting requests for participating addresses or manually adds addresses to the whitelist.
- During the token sale period, whitelisted participants send Ether to the contract address.
- The contract calculates the number of tokens to be allocated based on the Ether sent and the token price using this calculation
requiredEth = (token amount / 10**18) * token price
- The contract transfers the allocated tokens to the participants' addresses.
- The tokens sold counter and the participants' token balances are updated accordingly.
- At the end of the token sale, the contract owner calls the
finalize()
function to complete the sale. - The remaining tokens, if any, are transferred back to the contract owner.
- The contract owner can withdraw the Ether balance from the contract.
In this scenario, the token sale campaign fails to reach its goals. Here's a step-by-step walkthrough of the process:
- The contract owner deploys the Crowdsale contract with the desired parameters, such as token price, maximum tokens, sale start and end time, and purchase restrictions.
- The contract owner approves whitelisting requests for participating addresses or manually adds addresses to the whitelist.
- During the token sale period, participants send Ether to the contract address.
- The contract calculates the number of tokens to be allocated based on the Ether sent and the token price.
- If the token sale ends and the total tokens sold do not reach the minimum required, the contract owner decides to mark the campaign as failed.
- Participants can request refunds by calling the
refundCampaign()
function. - The contract transfers the purchased tokens back to the contract and refunds the corresponding Ether amount to the participants.
- Participants receive their refunds, and the token balances and tokens sold counter are adjusted accordingly.
The Crowdsale contract provides several functions for managing the token sale, whitelist, refunds, and other functionalities. Some of the key functions include:
buyTokens()
: Allows participants to purchase tokens by sending Ether to the contract address.requestWhitelist()
: Sends a whitelisting request to the contract owner.approveWhitelist()
: Approves a whitelisting request for a specific address.rejectWhitelist()
: Rejects the whitelisting request for a specific address.enableRefund()
: Enables refunds for participants after the token sale ends.disableRefund()
: Disables refunds for participants.withdrawBalance()
: Allows the contract owner to withdraw the contract's balance.- ... (Other functions for managing whitelisting, address status, and refunding)
Contributions to this project are welcome! If you have any ideas, suggestions, or bug reports, please submit an issue or create a pull request. Remember to adhere to the project's coding conventions and follow the code of conduct.
This project is licensed under the UNLICENSED license. Feel free to use, modify, and distribute the code as per your requirements. However, please note that no warranty is provided, and the authors shall not be liable for any damages or liabilities arising from the use of this software.