Setting Up a Multi-Stage Token Sale with Dynamic Pricing

A multi-stage token sale is a fundraising mechanism where token distribution occurs across sequential phases, each with its own pricing and allocation rules. Unlike a single fixed-price sale, this model allows projects to manage demand, reward early participants, and implement dynamic pricing strategies like a Dutch auction or a linear price increase. The core smart contract must manage state transitions between stages, enforce purchase limits, and calculate the correct token price based on the current block timestamp or tokens sold. This structure is common for fair launches and IDOs on platforms like SushiSwap's MISO.

The contract architecture requires several key state variables: a currentStage index, an array of SaleStage structs, and a total tokensSold counter. Each SaleStage should define its startTime, endTime, priceInWei, maxTokens, and potentially a priceIncreasePerSecond for dynamic stages. Access control is critical; functions like advanceStage should be restricted to an owner or a timelock controller. Purchase functions must validate the stage is active, that the buyer's contribution does not exceed personal or stage caps, and then calculate the token amount using (msg.value * PRECISION) / currentPrice().

Implementing dynamic pricing requires an on-chain price calculation. For a linear price increase, the formula in currentPrice() might be: startPrice + (priceIncreasePerSecond * (block.timestamp - stageStartTime)). It's essential to use a high precision multiplier (e.g., 1e18) to avoid rounding errors. Always perform multiplication before division in Solidity to maintain accuracy. Emit detailed events like StageAdvanced and TokensPurchased for off-chain indexing by frontends and analytics tools. Thorough testing with forked mainnet simulations using Foundry or Hardhat is non-negotiable to ensure price calculations and stage transitions behave correctly under network congestion.

Security considerations are paramount. Use OpenZeppelin's ReentrancyGuard and SafeERC20 libraries. Implement a withdrawFunds pattern that uses a pull-over-push mechanism to prevent reentrancy and failed transfer attacks. Clearly define what happens with unsold tokens: they can be burned, allocated to a treasury, or rolled into a subsequent stage. The contract should include an emergency pause function, but avoid complex upgradeability for a core sale contract due to the trust assumptions it introduces. A successful sale concludes with a token distribution phase, often involving a claim function that allows users to retrieve their tokens after a vesting period or immediate transfer.

Before writing any code, you must establish a secure development environment. This requires installing Node.js (v18 or later) and a package manager like npm or yarn. The core tool for this project is Hardhat, a leading Ethereum development framework. Install it globally or initialize it within your project directory. You will also need a code editor like VS Code with Solidity extensions for syntax highlighting and error checking. Finally, set up a Git repository to version control your smart contract code, which is a critical practice for collaboration and audit trails.

Your contract will interact with several key dependencies. The most important is OpenZeppelin Contracts, a library of secure, audited, and community-vetted smart contract components. You will import contracts for ERC-20 tokens (@openzeppelin/contracts/token/ERC20/ERC20.sol), safe math operations, and access control mechanisms like Ownable. For dynamic pricing logic, you may need a library for mathematical calculations, such as ABDKMath64x64 for fixed-point arithmetic, to avoid precision errors common with integer math in Solidity. Install these via npm: npm install @openzeppelin/contracts.

You need access to a blockchain for testing and deployment. For local development, Hardhat includes a built-in network. For testnets, configure RPC endpoints for networks like Sepolia or Goerli in your hardhat.config.js file. This requires test ETH, obtainable from faucets. You will also need a crypto wallet (e.g., MetaMask) and its private key or mnemonic phrase to sign transactions. Store these sensitive credentials securely using environment variables with a package like dotenv, and never commit them to your repository. Configure your Hardhat network settings to reference these variables.

A multi-stage sale with dynamic pricing involves complex state management. You must architect your contract to track distinct sale phases (e.g., seed, private, public), each with its own timing, contribution caps, and pricing model. The dynamic pricing mechanism—often a Dutch auction or a bonding curve—requires a precise, gas-efficient algorithm to calculate the current token price based on time elapsed or tokens sold. Plan your contract's storage layout and functions (startStage, buyTokens, updatePrice) carefully to avoid conflicts and ensure the logic is upgradeable or pausable if needed, using OpenZeppelin's ReentrancyGuard and Pausable contracts for security.

Thorough testing is non-negotiable for a financial contract. Write comprehensive unit and integration tests using Hardhat's testing framework paired with Chai for assertions. Simulate all sale stages, test edge cases like contract pausing, maximum cap breaches, and the dynamic price calculation at various points. Use Hardhat's console.log for debugging and consider property-based testing with fuzzing to uncover unexpected inputs. Before mainnet deployment, conduct an audit or use static analysis tools like Slither or MythX. Finally, verify and publish your contract source code on block explorers like Etherscan using the Hardhat verification plugin.

A multi-stage token sale with dynamic pricing is a common fundraising mechanism in Web3, allowing projects to manage capital influx and reward early participants. Unlike a simple fixed-price sale, this architecture segments the sale into distinct phases—such as a private round, a public presale, and a public sale—each with its own pricing logic and allocation. The dynamic pricing component automatically adjusts the token price based on predefined triggers, like time elapsed or tokens sold, using mechanisms like a bonding curve or a linear price decay function. This creates a fair and transparent distribution model that is executed entirely on-chain.

The core contract architecture typically involves several key components. A central sale contract acts as the primary interface, managing the overall state and funds. It interacts with a pricing module—a separate contract or internal library—that calculates the current token price based on the sale's phase and progress. An allocation manager handles vesting schedules and claim logic for different participant tiers. Crucially, the sale contract must also integrate with the project's ERC-20 token contract for minting or transferring tokens upon purchase. Security considerations like access control (using OpenZeppelin's Ownable or roles), pausability, and reentrancy guards are non-negotiable for protecting user funds.

Implementing the dynamic pricing logic requires careful mathematical design. A common approach is a linear price decay, where the price decreases at a fixed rate per block or over set time intervals until a floor price is reached. For example, a sale might start at 0.1 ETH per token and decrease by 0.001 ETH every 100 blocks. This can be implemented in Solidity as:

solidityCopy
function currentPrice() public view returns (uint256) {
    uint256 blocksElapsed = block.number - saleStartBlock;
    uint256 discount = (blocksElapsed / blocksPerDiscount) * discountPerStep;
    return startPrice > discount ? startPrice - discount : floorPrice;
}

Alternatively, a bonding curve contract, where price is a function of tokens sold, can create a smooth, demand-driven price discovery mechanism.

Managing multiple sale stages requires robust state management. Each stage should have clearly defined parameters: a startTime and endTime, a maxContribution per address, a stageCap for total raise, and a reference to its specific pricing function. Transitions between stages can be time-based or manually triggered by an admin after a stage cap is met. It's critical to ensure that purchase functions correctly validate the current active stage, apply the right price, and enforce contribution limits. Events like StageAdvanced and TokensPurchased should be emitted for off-chain monitoring. Using a modular design with separate contracts for each stage can improve upgradability and testing but increases deployment complexity.

After the sale concludes, the contract must facilitate the secure distribution of tokens and funds. Purchased tokens are often held in the contract until a claim period begins, preventing immediate dumping on the market. The claim function allows users to withdraw their tokens, often with vesting logic applied. Raised funds (ETH or other native currency) should be withdrawable by the project team via a secure withdrawal pattern, typically requiring a timelock or multi-signature wallet. A final security audit from a firm like ChainSecurity or CertiK is essential before mainnet deployment to review the pricing math, access controls, and fund flow for vulnerabilities.

Dynamic pricing is a mechanism where a token's sale price changes automatically based on predefined rules. Unlike a fixed-price sale, it allows projects to implement strategies like a Dutch auction (price decreases over time), a bonding curve (price increases with supply sold), or a tiered sale with distinct price points. This approach can help manage demand, optimize fundraising, and reduce gas wars. In Solidity, this logic is implemented within the sale contract's buy function, where the current price is calculated on-chain before processing the purchase.

The core of the system is a pricing function that returns the current price per token. For a time-based Dutch auction, you might store a startPrice, endPrice, startTime, and duration. The price decays linearly: currentPrice = startPrice - ((block.timestamp - startTime) * (startPrice - endPrice) / duration). For a supply-based bonding curve, you track tokensSold and use a formula like currentPrice = basePrice + (tokensSold * priceIncreasePerToken). It's critical to use SafeMath libraries or Solidity 0.8.x's built-in overflow checks for these calculations.

A multi-stage sale combines these concepts, segmenting the sale into distinct phases. You might have a seed round with a low, fixed price, followed by a public auction phase. The contract must manage state transitions, often controlled by the owner or a timer. Implement a state variable like enum SaleStage { NotStarted, Seed, Auction, Ended }. Modifiers like onlyDuringStage(SaleStage.Auction) restrict function access. Each stage can have its own pricing function, hard cap, and wallet limits, allowing for complex fundraising strategies within a single contract.

When a user calls buyTokens(uint256 amount), the contract must: 1) Check the sale is active (require(currentStage == SaleStage.Auction)), 2) Calculate the currentPrice using the logic for the active stage, 3) Validate the user's payment (msg.value >= amount * currentPrice), 4) Update state (tokensSold += amount;), and 5) Transfer tokens to the buyer. Always refund any excess ETH sent. Emit a detailed TokensPurchased event with buyer, amount, price, and stage for transparency.

Security and fairness are paramount. Use pull-over-push for withdrawals to avoid reentrancy; let users claim tokens after the sale. Implement a timelock or multi-sig for stage advancement and finalization. Thoroughly test pricing math for edge cases: at startTime, at endTime, and when caps are reached. Tools like Foundry fuzzing can help ensure the pricing function behaves correctly under all inputs. Always audit the final contract, as pricing logic is a frequent source of financial bugs.

A multi-stage token sale with dynamic pricing is a sophisticated fundraising mechanism where a project's native tokens are sold to investors in sequential phases, each with its own price and supply parameters. This model, often used for Initial DEX Offerings (IDOs) or community sales, allows for price discovery and fairer distribution compared to a single fixed-price event. The sale is governed by a smart contract that enforces access control—determining who can participate and when—and automatically adjusts the token price based on predefined rules, such as time elapsed or percentage of tokens sold. This creates a transparent and automated process that reduces manual intervention and potential manipulation.

The core smart contract architecture typically involves several key components: a sale manager contract that orchestrates the stages, a pricing module that calculates the current token price, and a vesting contract that locks purchased tokens for a specified duration. For dynamic pricing, common models include a linear Dutch auction, where the price decreases over time until all tokens are sold, or a tiered pricing model, where the price increases at specific milestones (e.g., after 25%, 50%, and 75% of the stage's supply is sold). The contract must also implement robust access control, often using OpenZeppelin's Ownable or role-based AccessControl libraries, to restrict functions like advancing stages or withdrawing funds to authorized addresses only.

Here is a simplified Solidity code snippet illustrating the structure for a two-stage sale with a linear price decrease (Dutch auction) in the first stage. This example uses a SaleStage struct and a public currentPrice variable that updates based on time.

solidityCopy
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

contract MultiStageSale {
    using SafeERC20 for IERC20;

    struct SaleStage {
        uint256 startTime;
        uint256 duration;
        uint256 startPrice;
        uint256 endPrice;
        uint256 tokensForSale;
        uint256 tokensSold;
        bool isActive;
    }

    SaleStage[] public stages;
    IERC20 public saleToken;
    address public treasury;
    uint256 public currentStageIndex;

    constructor(IERC20 _saleToken, address _treasury) {
        saleToken = _saleToken;
        treasury = _treasury;
        // Initialize stages in constructor or via an admin function
    }

    function getCurrentPrice() public view returns (uint256) {
        SaleStage memory stage = stages[currentStageIndex];
        if (!stage.isActive) return 0;

        uint256 timeElapsed = block.timestamp - stage.startTime;
        if (timeElapsed >= stage.duration) return stage.endPrice;

        // Linear price decrease from startPrice to endPrice
        uint256 priceRange = stage.startPrice - stage.endPrice;
        return stage.startPrice - (priceRange * timeElapsed) / stage.duration;
    }

    function purchaseTokens(uint256 amount) external payable {
        SaleStage storage stage = stages[currentStageIndex];
        require(stage.isActive, "Stage not active");
        require(stage.tokensSold + amount <= stage.tokensForSale, "Exceeds stage supply");

        uint256 price = getCurrentPrice();
        uint256 cost = price * amount;
        require(msg.value >= cost, "Insufficient payment");

        stage.tokensSold += amount;
        // Transfer sale tokens to buyer (to be vested later)
        // Implement refund logic for excess payment
    }
    // ... functions to advance stages, withdraw funds, and integrate vesting
}

Integrating a vesting schedule is critical for aligning long-term incentives. Purchased tokens should not be immediately liquid; instead, they are locked in a separate vesting contract that releases them linearly over time. For example, a 12-month vesting schedule with a 3-month cliff means no tokens are released for the first 3 months, after which 25% of the tokens unlock, followed by linear monthly releases for the remaining 9 months. This prevents immediate sell-pressure post-sale. The sale contract mints or allocates tokens to the vesting contract upon purchase, which then becomes the sole entity responsible for dispensing tokens to beneficiaries according to its schedule. Popular audited templates for this include OpenZeppelin's VestingWallet.

Security and operational considerations are paramount. The contract must be thoroughly audited, as it will hold significant user funds. Key risks include price oracle manipulation, reentrancy attacks on purchase functions, and improper access control leading to unauthorized stage modifications. Use established libraries like OpenZeppelin for security primitives. Furthermore, the front-end interface must accurately fetch and display the real-time price from the contract's getCurrentPrice function. Post-sale, mechanisms must be in place for the project team to withdraw raised funds (in ETH or stablecoins) and for any unsold tokens to be handled (e.g., burned or returned to the treasury). Proper event emission for all purchases and stage changes is essential for off-chain tracking and transparency.

Begin with a comprehensive unit testing suite using frameworks like Foundry or Hardhat. Test core logic in isolation: the bonding curve calculations, stage transition triggers, and price update mechanisms. For a dynamic pricing model, write tests that simulate edge cases like rapid purchases depleting a stage's allocation, verifying the price adjusts correctly according to your formula (e.g., linear, exponential). Mock external dependencies like the token contract and payment receiver to ensure your sale contract behaves predictably in a controlled environment.

Proceed to integration testing by deploying your sale contract with a mock ERC-20 token on a local fork or testnet like Sepolia. Simulate the entire user journey: a buyer approving funds, making a purchase, and receiving tokens. Test critical interactions such as the contract pulling funds via transferFrom and minting tokens. Use tools like Tenderly or Hardhat console to inspect state changes after each transaction, confirming that the total raised, tokens distributed, and current price are updated atomically and accurately.

For staging deployment, use a testnet that closely mirrors mainnet conditions, such as Sepolia or Holesky. Conduct end-to-end tests with real wallets (e.g., MetaMask) and small amounts of test ETH. This phase validates the frontend integration, wallet connectivity, and real-world transaction flow. It's also the stage to perform a security audit or engage with bug bounty platforms. All discovered issues must be fixed and regression-tested before proceeding to the final deployment phase.

The final mainnet deployment should follow a structured process. First, verify and publish the source code on Etherscan or Blockscout. Use a timelock controller or multisig wallet for the contract's owner functions, such as withdrawing funds or pausing the sale. Deploy the sale contract with all parameters finalized—start time, stage durations, initial price, and curve parameters. Monitor the first few transactions closely using a block explorer and set up alerting for any unexpected reverts or gas spikes.

You have now implemented a system that can manage multiple sale phases (e.g., seed, private, public) with distinct pricing models. The core contract uses a SalePhase struct to define parameters like startTime, endTime, price, and maxPerWallet. Dynamic pricing was achieved through mechanisms like a Dutch auction (price decreases over time) or a tiered pricing model (price increases as allocation fills). Key security features include a timelock for admin functions, a withdraw pattern for funds, and comprehensive input validation to prevent common vulnerabilities like integer overflows.

For production deployment, several critical steps remain. First, conduct a thorough audit of your TokenSale.sol contract. Engage a reputable firm or use automated tools like Slither or Mythril. Next, implement a robust testing suite using Hardhat or Foundry, simulating edge cases like phase transitions, maximum purchase limits, and contract pausing. You must also decide on a frontend framework—React with ethers.js or Vue with wagmi are popular choices—and ensure it correctly fetches real-time phase data and pricing from your contract.

Consider extending the system's functionality. You could integrate a vesting contract that locks purchased tokens and releases them linearly over time, which is a standard requirement for early investor rounds. Another advanced feature is implementing a refund mechanism if a sale fails to meet its soft cap, protecting participant funds. For broader accessibility, explore cross-chain sale deployments using LayerZero or Axelar to allow purchases from multiple blockchain networks, though this adds significant complexity to the architecture.

The final step is planning the launch sequence. This includes: deploying the ERC-20 token contract, deploying and configuring the sale contract, setting up a multisig wallet for the treasury, conducting a test sale on a testnet with a small group, and finally, executing the mainnet deployment. Always ensure clear, transparent communication with your community regarding sale timelines, eligibility, and token distribution schedules. Your contract's verified source code and a detailed FAQ are essential for building trust.