feat: CrowdFunding Vending Machine smart contract (fixes #7)

.gitignore

@@ -0,0 +1,11 @@
+node_modules
+.env
+coverage
+coverage.json
+typechain
+typechain-types
+
+# Hardhat files
+cache
+artifacts
+

README.md

@@ -1,2 +1,42 @@
-# Hackathon
-Tasks related to official Defiville hackathons
+# Defiville Hackathon - CrowdFunding Vending Machine
+
+Smart contract implementation and test suite for the **1° Defiville Hackathon - CrowdFounding Vending Machine** (Issue #7).
+
+## Overview
+
+The `CrowdFundingVendingMachine` smart contract provides a decentralized mechanism to create and manage presale / crowdfunding campaigns for upcoming products (NFTs, ERC20 tokens, physical products, perks, etc.).
+
+### Key Features & Lifecycle
+- **Campaign Creation**: Any creator or organization can open a crowdfunding presale with a metadata URI (`productURI`), funding goal (`goal`), unit price (`price`), campaign duration (`duration`), and maximum capacity (`supply`).
+- **Supporter Pledges**: Backers pledge ETH to reserve units of upcoming items.
+- **Product Redemption**: Once a campaign reaches its goal, backers can redeem their reserved product units.
+- **Creator Settlement**: Upon goal attainment, creators can withdraw the pledged proceeds.
+- **Cancellation & Refunds**: If a campaign expires without meeting the funding target or is cancelled by the creator, backers can claim full refunds through a gas-optimized pull mechanism.
+
+### Core Interface
+- `createCrowdCampaign(string productURI, uint256 goal, uint256 price, uint256 duration, uint256 supply) returns (uint256 campaignId)`
+- `supportCampaign(uint256 campaignId, uint256 quantity) payable`
+- `redeemProduct(uint256 campaignId, uint256 quantity)`
+- `claimFunds(uint256 campaignId)`
+- `cancelCampaign(uint256 campaignId)`
+- `refund(uint256 campaignId)`
+- `stateOf(uint256 campaignId) view returns (CampaignState)`
+- `getCampaign(uint256 campaignId) view returns (Campaign, CampaignState)`
+- `getSupporterInfo(uint256 campaignId, address supporter) view returns (uint256 quantity, uint256 amount, uint256 redeemed, uint256 redeemable)`
+
+## Development & Testing
+
+### Installation
+```bash
+npm install
+```
+
+### Compile Contracts
+```bash
+npx hardhat compile
+```
+
+### Run Tests
+```bash
+npx hardhat test
+```