SealedBidTokenSale

script/migrations/155-deploy-sale.s.sol

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.18;
+
+import {SealedBidTokenSale} from "@kinto-core/apps/SealedBidTokenSale.sol";
+
+import {SafeBeaconProxy} from "@kinto-core/proxy/SafeBeaconProxy.sol";
+import {KintoAppRegistry} from "@kinto-core/apps/KintoAppRegistry.sol";
+
+import {UUPSProxy} from "@kinto-core-test/helpers/UUPSProxy.sol";
+import {MigrationHelper} from "@kinto-core-script/utils/MigrationHelper.sol";
+
+import "@kinto-core-test/helpers/ArrayHelpers.sol";
+import {Script} from "forge-std/Script.sol";
+import {console2} from "forge-std/console2.sol";
+
+contract DeployScript is Script, MigrationHelper {
+    using ArrayHelpers for *;
+
+    address public constant SOCKET_APP = 0x3e9727470C66B1e77034590926CDe0242B5A3dCc;
+    address public constant KINTO = 0x010700808D59d2bb92257fCafACfe8e5bFF7aB87;
+    address public constant TREASURY = 0x793500709506652Fcc61F0d2D0fDa605638D4293;
+    address public constant USDC = 0x05DC0010C9902EcF6CBc921c6A4bd971c69E5A2E;
+    //Tuesday, Feb 11, 2025, 10:00:00 AM PT.
+    uint256 public constant PRE_START_TIME = 1739296800;
+    //Tuesday, Feb 18, 2025, 10:00:00 AM PT.
+    uint256 public constant START_TIME = 1739901600;
+    uint256 public constant MINIMUM_CAP = 250_000 * 1e6;
+
+    function run() public override {
+        super.run();
+
+        if (_getChainDeployment("SealedBidTokenSale") != address(0)) {
+            console2.log("SealedBidTokenSale is deployed");
+            return;
+        }
+
+        vm.broadcast(deployerPrivateKey);
+        SealedBidTokenSale impl = new SealedBidTokenSale(KINTO, TREASURY, USDC, PRE_START_TIME, START_TIME, MINIMUM_CAP);
+
+        (bytes32 salt, address expectedAddress) =
+            mineSalt(keccak256(abi.encodePacked(type(UUPSProxy).creationCode, abi.encode(address(impl), ""))), "5A1E00");
+
+        vm.broadcast(deployerPrivateKey);
+        UUPSProxy proxy = new UUPSProxy{salt: salt}(address(impl), "");
+        SealedBidTokenSale sale = SealedBidTokenSale(address(proxy));
+
+        _handleOps(
+            abi.encodeWithSelector(
+                KintoAppRegistry.addAppContracts.selector, SOCKET_APP, [address(sale)].toMemoryArray()
+            ),
+            address(_getChainDeployment("KintoAppRegistry"))
+        );
+
+        uint256[] memory privateKeys = new uint256[](1);
+        privateKeys[0] = deployerPrivateKey;
+        _handleOps(
+            abi.encodeWithSelector(SealedBidTokenSale.initialize.selector),
+            payable(kintoAdminWallet),
+            address(proxy),
+            0,
+            address(0),
+            privateKeys
+        );
+
+        assertEq(address(sale), address(expectedAddress));
+        assertEq(address(sale.USDC()), USDC);
+
+        saveContractAddress("SealedBidTokenSale", address(sale));
+        saveContractAddress("SealedBidTokenSale-impl", address(impl));
+    }
+}

src/apps/SealedBidTokenSale.md

@@ -0,0 +1,164 @@
+# SealedBidTokenSale Technical Specification
+
+Below is the **technical specification** for a Solidity **sealed‐bid** token sale contract.
+
+---
+
+## 1. **Contract Overview**
+
+- **Name**: `SealedBidTokenSale`  
+- **Purpose**: Accept USDC deposits for a token sale, enforce timing and minimum cap requirements, enable refunds if the sale is unsuccessful, and distribute tokens and USDC allocations via a Merkle proof if successful.
+- **Inheritance**: `Ownable`, `ReentrancyGuard`
+
+---
+
+## 2. **Key Roles**
+
+- **Owner**:  
+  - Inherits from OpenZeppelin `Ownable`.  
+  - Sets crucial parameters during contract deployment.  
+  - Controls sale finalization, Merkle root setting, and proceeds withdrawal.
+
+- **Participants**:  
+  - Deposit USDC during the sale window.  
+  - Withdraw their deposit if the sale fails.  
+  - Claim tokens and USDC allocations after sale success using a Merkle proof.
+
+- **Treasury**:  
+  - Immutable address specified at deployment.  
+  - Receives USDC proceeds upon successful sale completion.
+
+---
+
+## 3. **Immutable Parameters**
+
+1. **`saleToken`** (`IERC20`)  
+   - Token being sold through the contract.
+   - Set at construction.
+
+2. **`USDC`** (`IERC20`)  
+   - USDC token contract reference for deposits.
+   - Set at construction.
+
+3. **`treasury`** (`address`)  
+   - Fixed address that receives proceeds.
+   - Set at construction.
+
+4. **`startTime`** (`uint256`)  
+   - Sale start timestamp.
+   - Set at construction.
+
+5. **`minimumCap`** (`uint256`)  
+   - Minimum USDC required for success.
+   - Set at construction.
+
+---
+
+## 4. **State Variables**
+
+1. **`saleEnded`** (`bool`)  
+   - Indicates if owner has ended the sale.
+
+2. **`capReached`** (`bool`)  
+   - Set to `true` if `totalDeposited >= minimumCap` when sale ends.
+
+3. **`totalDeposited`** (`uint256`)  
+   - Sum of all USDC deposits.
+
+4. **`merkleRoot`** (`bytes32`)  
+   - Root hash for token and USDC allocation proofs.
+
+5. **`deposits`** (`mapping(address => uint256)`)  
+   - Tracks each user's USDC deposit amount.
+
+6. **`hasClaimed`** (`mapping(address => bool)`)  
+   - Records whether an address has claimed their allocation.
+
+---
+
+## 5. **Core Functions**
+
+### 5.1 **`deposit(uint256 amount)`**
+- **Purpose**: Accepts USDC deposits from participants.  
+- **Constraints**:  
+  1. Must be after `startTime`.
+  2. Sale must not be ended.
+  3. Amount must be non-zero.
+- **Effects**:  
+  - Updates `deposits[msg.sender]` and `totalDeposited`.
+  - Transfers USDC from sender to contract.
+  - Emits `Deposited` event.
+
+### 5.2 **`withdraw()`**
+- **Purpose**: Returns USDC to depositors if sale fails.  
+- **Constraints**:  
+  1. Sale must be ended.
+  2. Cap must not be reached.
+  3. Caller must have non-zero deposit.
+- **Effects**:  
+  - Returns user's entire USDC deposit.
+  - Zeroes their deposit balance.
+  - Emits `Withdrawn` event.
+
+### 5.3 **`endSale()`** (Owner-only)
+- **Purpose**: Finalizes sale and determines success.  
+- **Constraints**:  
+  1. Only callable by owner.
+  2. Sale must not already be ended.
+- **Effects**:  
+  - Sets `saleEnded = true`.
+  - Sets `capReached` based on minimum cap check.
+  - Emits `SaleEnded` event.
+
+### 5.4 **`claimTokens(uint256 saleTokenAllocation, uint256 usdcAllocation, bytes32[] calldata proof, address user)`**
+- **Purpose**: Processes token and USDC claims using Merkle proofs.  
+- **Constraints**:  
+  1. Sale must be ended and successful.
+  2. Merkle root must be set.
+  3. User must not have claimed.
+  4. Valid Merkle proof required.
+- **Effects**:  
+  - Marks user as claimed.
+  - Transfers allocated sale tokens.
+  - Returns allocated USDC.
+  - Emits `Claimed` event.
+
+### 5.5 **`setMerkleRoot(bytes32 newRoot)`** (Owner-only)
+- **Purpose**: Sets allocation Merkle root.
+- **Constraints**:  
+  1. Sale must be ended and successful.
+  2. Only callable by owner.
+- **Effects**:  
+  - Sets `merkleRoot`.
+  - Emits `MerkleRootSet` event.
+
+### 5.6 **`withdrawProceeds()`** (Owner-only)
+- **Purpose**: Sends USDC to treasury.
+- **Constraints**:  
+  1. Sale must be ended and successful.
+  2. Only callable by owner.
+- **Effects**:  
+  - Transfers all USDC to treasury address.
+
+---
+
+## 6. **Custom Errors**
+
+1. **Parameter Validation**:
+   - `InvalidSaleTokenAddress`
+   - `InvalidTreasuryAddress`
+   - `ZeroDeposit`
+
+2. **State Checks**:
+   - `SaleNotStarted`
+   - `SaleAlreadyEnded`
+   - `SaleNotEnded`
+   - `CapNotReached`
+   - `SaleWasSuccessful`
+
+3. **Claim Validation**:
+   - `NothingToWithdraw`
+   - `AlreadyClaimed`
+   - `InvalidProof`
+   - `MerkleRootNotSet`
+