Launchpad contract development: where the token sale breaks
The token sale contract is the most loaded part of a launchpad: it receives funds first, releases tokens last, and remains publicly readable after launch.
Mistakes in the whitelist here are not abstract: an address that appears in the list twice — as a wallet and as an intermediary contract — gets a doubled allocation, and the distribution drifts before the sale even opens.
A separate problem is when the limit is calculated by the sender's address: one participant creates several wallets and passes the cap on each, pushing others out of the round.
Double participation in the sale usually surfaces after closing, when it is too late to calculate: amounts are collected, and allocations have to be reassembled manually.
A stuck unlock schedule is the second classic of a DIY build: the claim is calculated from the start time rather than the actual contribution, or token transfers before the deadline are unrestricted, and unlocking costs a couple of transactions.
Disputed allocations between rounds add a third problem — the priority of bids is not fixed, and the distribution queue is determined by whoever managed to send the transaction first.
The price is the same for all scenarios: refunds, manual recalculation, and investors who will not come to the next launch.
The sale contract is designed so that no disputed areas remain at the logic level: the whitelist is assembled into a deterministic tree with uniqueness verification, the contribution size is calculated from the signer, and vesting holds its own balance and does not allow bypassing the deadline with transfers. Below we break down how this is closed in launchpad contract development.
Sale logic: whitelist, allocations, and unlock schedule
The participant list is not copied into the contract line by line — only the root of the hash tree is stored, and the address comes to the purchase with proof of inclusion and its allocation amount.
Therefore, the sale withstands tens of thousands of addresses, the state snapshot is fixed at a specific block, and editing one entry does not require rebuilding the contract.
Allocation and purchase limits are checked at a single point: personal cap, round cap, and total sale size. An excess is not silently trimmed — the transaction is rejected, and the participant sees the reason, not a reduced share.
The round price is set by config, so subsequent rounds are launched by changing parameters rather than new code.
Vesting is built on the principle of "everything accrued, but not everything withdrawable": a waiting period, then linear unlocking from the sale start.
Each participant claims tokens themselves with a separate call — the contract does not send balances in a loop over an array, so the cost of the operation does not grow with the number of holders.
This removes the main class of withdrawal failures: a failure for one address does not block the others. We take roles, pause, and reentrancy protection from ready, proven libraries OpenZeppelin rather than writing them ourselves.
The effect is measurable: a repeat round means zero manual address edits, allocation reconciliation means comparing one hash instead of parsing an export line by line, and disputed accruals are resolved using the state snapshot root.
Launch formats: custom contract, factory, platform module
The launch format determines how much code we write once and how much we reuse. A custom sale contract gives full control over rounds, wallet limits, and the unlock schedule, but audit and support fall entirely on us.
A factory deploys copies of an already verified template, while a platform module adds a ready admin panel, share accounting, and list-based admission.
The choice comes down to the distribution model: how many rounds and price levels, how the admission list is formed, whether there are refunds, and exactly how vesting unlocks.
If the rules are non-standard in at least one point, the template will have to be modified — and it is easier to resolve this before launch than to migrate state afterward.
Comparison of launch formats
| Format | When it fits | Limitations |
|---|---|---|
| Custom sale contract | Non-standard rounds, private terms, wallet limits, integration with external services | Full audit and support cycle, longer to launch, we write the admin panel and accounting ourselves |
| Factory contract | A series of sales under identical rules, several projects under one management | The template is fixed: deviations require a new version, an error is replicated to all copies |
| Platform module | Standard rounds, ready admission list, template vesting, launch within tight deadlines | Logic is limited by the platform's framework, some parameters are unavailable, dependency on its updates |
Changing the format on a live sale is a separate task: admission snapshots, accumulated shares, and open claims are migrated, while previous contracts remain read-only. Therefore, we choose the format for the final distribution model, not for the speed of the first round.
Work stages: from distribution model to handover of control
We do not start writing code until the sale model is fixed on paper: a contract on the blockchain cannot be quietly corrected after publication, and an error in round calculation or payout schedule costs more than an extra day of coordination.
That is why the contract development stages are arranged so that each ends with a verifiable artifact — a specification, a role diagram, or a test run.
- Distribution model breakdown: rounds, per-participant limits, token price, pause before the first accruals, team and reserve shares. We fix it with a one-page specification with calculation examples.
- Role and access diagram: who maintains the whitelist, who opens the round, who withdraws funds. We separately note which rights are given to multisig and which are burned after the final round.
- Contract assembly: sale, token, vesting, and distribution — as separate modules with a shared balance and limit accounting scheme.
- Contract verification: tests cover repeat bids, round overflow, early withdrawal, sale cancellation, and administrator operation.
- Test sale launch on a network copy: full purchase cycle, scheduled accrual and withdrawal, reconciliation of volumes and payout order.
- Contract handover: publication, transfer of control to the customer, role documentation, and a memo for supporting the first round.
Handover package: contracts, diagrams, policies, and procedures
Project handover is not only access and deployed code. We provide a package that brings a new team up to speed in one review: what is configured where, who manages what, how to act in case of failure. Below is exactly what remains with the customer.
- Contract documentation — purpose of modules, deployment parameters (stage price, limits, sale windows), list of owner functions and points where a parameter change affects already running sales.
- Distribution diagram — route of funds from buyer to the project fund, liquidity pool, and reserve, rules for moving a payout to the next status, and the moment from which withdrawal becomes available.
- Access role matrix — who adds addresses to the whitelist, who changes the unlock schedule, who stops trading; which operations require two confirmations and how to transfer rights when the administrator changes.
- Administrator instruction — scenarios for typical operations (starting a stage, adding participants, early completion, withdrawing funds) with a list of parameters to check and an analysis of transaction events.
- Support procedure — frequency of checks, configuration update order, key storage and rotation, and the boundary of our responsibility after handover.
- Incident procedure — what to do with a stuck transaction, an error in stage price, or signs of key compromise: first action, circle of responsible people, and procedure for recording traces.
Case: sale with a whitelist and unlock schedule
The platform was running a sale with a whitelist and an unlock schedule. Before us, crediting was manual: an operator checked bids, added addresses in batches, and calculated shares separately in a spreadsheet.
At peak, this produced a queue of bids for several hours and errors in amounts that were found only after the round closed.
We rewrote the sale circuit: the contract accepts an address only upon confirmation from the whitelist, the share is fixed at the moment of crediting, and the unlock schedule is set by a timetable inside the contract.
The participant calls the unlock themselves — the operator is not involved. We took the basic token and vesting implementations from OpenZeppelin, and tests covered scenarios with early withdrawal and repeat crediting.
What changed in the metrics
| Metric | Before | After |
|---|---|---|
| Manual operations during crediting | each bid manually | 0, only role granting |
| New campaign launch | 4-5 days | one business day |
| Unlock requests | 50-60 per week | isolated |
| Transaction failures at peak | 10-15% of bids | 0 |
| Share calculation incidents | 3-4 per campaign | 0 |
Peak failures were eliminated with a queue: bids are collected into batches, retries are sent automatically, and the gas reserve is set in advance. Support stopped being a bottleneck — the freed-up hours went to preparing the next round.
What to do if the sale is already running and the unlock terms change
Short answer: changes cannot be made to a deployed contract — it can only be replaced entirely or have a new layer built alongside it.
The choice depends on two facts: whether the campaign tokens and funds are held inside the old contract, and whether it has a controllable implementation with pause.
Hence three working scenarios: contract migration, an add-on on top of the current one, and a second campaign with clean rules.
Migration is the most predictable option. At a fixed block, we take a snapshot: addresses, paid amounts, allocation sizes, and what has already been received according to the schedule.
In the new contract, assembled on proven OpenZeppelin libraries, the participant confirms the same data, and the unlock schedule change applies only to the not-yet-issued part. We switch the old contract to read-only mode so that double claiming is technically impossible.
An add-on is cheaper in terms of risk when the sale and vesting are separated: the sale holds the price, limits, and whitelist, while unlocking is handled by a separate contract.
Then updating the sale rules means deploying a new vesting contract and switching the pointer to it, and participants do not re-sign anything.
A second campaign is appropriate when terms cannot be changed retroactively: we close the current sale as is, transfer the remaining undistributed allocations to a new pool, and fix the rules anew.
What to choose is decided by the administrator rights in the contract and the presence of a pause mechanism — this determines whether the migration proceeds automatically or requires manual transfer of participants.
Technical questions on sale launch and access roles
Before publishing the sale contract, we separate two sets: what is set at deployment and what remains changeable.
Price, round window, hard cap, and wallet limit are written into immutable fields; only pre-declared switches change — purchase pause and early completion upon reaching the cap. Below are short answers to the doubts most often raised before launch.
Can the round terms be changed after publication?
No. They can only be updated with a new sale contract with explicit migration and announcement. Every pause or completion call is recorded by an event — the sale state is visible in the block explorer.
How does the contract verify an address's right to purchase?
The list is hashed off-chain into a tree, the contract stores only the root, and the buyer presents proof — the state remains compact, and verification costs the same for any list size.
The second option is a signature with a limited validity period, convenient for private rounds without publishing the list. In both cases, the recipient's address is checked, so the right cannot be forwarded to another wallet.
Who do administrative rights transfer to after launch?
To the project's multisig, not to a single developer key. For critical operations, we configure an execution delay: a declared action takes effect after a set interval and is visible on-chain the whole time — there is time to react before execution. After token unlocking, administrative functions are removed completely.
What is checked before contract publication?
A testnet run through scenarios: purchase above the limit, reentering the purchase function, purchase outside the round window, attempting to claim tokens before unlocking.
Then an independent audit and reconciliation of the published code with the verified version — discrepancies in share calculation and unlock schedule are found before launch, not after.
Let's discuss the task and come back with a sale work plan
So that the estimate and work plan for launching a token sale are concrete, rather than "plus or minus based on experience with similar projects," we need inputs from the customer.
Without them, it is unclear where the main difficulty lies: in round mechanics, legal restrictions by buyer country, or wallet integrations.
What needs to be sent so that we come back with a calculation:
- Network and token standard: EVM-compatible, Solana, or a custom network — the contract architecture and wallet support depend on this.
- Round mechanics: fixed price, staged by rounds or auction, wallet limits, fundraising targets, and refund terms if the threshold is not reached.
- Whitelist rules: manual address list, Merkle tree, signature from your server, or open purchase with identity verification.
- Vesting and claim: cliff, linear or staged schedule, market listing date, and how undistributed tokens are handled.
- Tokenomics: distribution, treasury addresses, referral accruals, where sale proceeds go.
- Payment acceptance: which assets and networks we accept, whether automatic refunds are needed.
- Access and control: who owns administrative roles, whether multisig is required, whether an independent audit and transfer of rights to the customer's team are planned.
In response, we send a contract diagram with roles and fund flows, work stages with order and dependencies, and the composition of what we hand over after launch — source code, access policies, and support instructions.
The plan commits to neither scope nor deadlines: it can be taken as a whole, started with one token sale contract, or postponed. Describe the task — we will come back with an estimate and work plan.