#D17 Contract Suite - Technical Reference (V15.1)

Audience: Solidity/EVM engineers integrating with, extending, or reviewing the suite. Citation convention: File.sol:line paths are relative to the contracts/contracts/ directory and point to the V15.1 source in this repository. The rule-level changes from the upstream V14 suite, and the V15.1 fixes, are summarised in V15_HARDENING.md.

#1. Overview & scope

Status: npm run test:contracts green - 517/517 assertions in test/local-e2e.mjs, 51/51 in test/hardening-e2e.mjs, 36/36 in test/mainnet-floors-e2e.mjs, 25/25 in test/fee-splitter-e2e.mjs, 17/17 in test/v15-1-regressions-e2e.mjs, and the four V15.1 review suites (failed-refund-remediation 80 checks, adversarial-callbacks 32, minimum-liquidity 4, rounding-reference-model 84,000), see §10. Stateful fuzz test/fuzz-invariants.mjs passes on V15.1. Slither 0.11.6 reports no exploitable finding. V15.1 is deployed on Ethereum mainnet (factory 0xB46eb48f982b63B879E00592880D12d1741fDB02) and on Sepolia (factory 0x260cbEA5Af1669446353d2B80D75a145016C1228). It was reviewed by the project lead's Solidity reviewer and has not received a formal professional third-party audit.

D17 is a five-round fair-launch protocol on a Uniswap-V2-style AMM. Users commit ETH (wrapped to WETH) through personal escrow contracts ("lockers"); round 0 discovers an anchor price and every later round sells at or above it; refund windows follow rounds 0–3 and every refund pays a penalty into the liquidity vault; after finalization each locker settles - sale tokens to the buyer, a treasury fee, a protocol fee, and the remainder into the liquidity vault. Pool creation is permissionless once every final commitment is settled; anyone can settle absent users after the grace period, one locker at a time or up to 4 per call through D17LockerFactory.settleAfterGraceBatch, so nobody can block it. The pool pairs the exact sum of every locker's pool share plus all refund penalties with the whole (sale-scaled) LP token allocation, in one deposit; no liquidity is ever added after trading opens. If round 0 misses its minimum the launch fails and every buyer gets back all of their WETH, including the penalties paid in round 0's refund window. All admin authority in the creation path is destroyed before the first launch can exist (one-shot pins, mint close, ownership renounce, enforced on-chain). The only owner that may survive is D17FeeConfig's, which can only set the protocol fee (≤ 2%) for future launches; on Ethereum mainnet the factory refuses to create a launch until that owner is renounced too.

#2. Topology

   ┌────────────────┐ currentFee()  ┌──────────────────────────────────────────────────┐
   │ D17FeeConfig   │◄──────────────│ D17Factory  (entry point, config validation,     │
   │ (fee ≤ 2%,     │  owner() on   │  fee snapshot, launch + locker registries)       │
   │  renounced on  │  mainnet      └───┬──────────────────────────────────┬───────────┘
   │  mainnet)      │                   │ onlyD17Factory                   │ registerLockerFor
   └────────────────┘ createLaunch(cfg) │                                  │ (pinned lockerFactory)
                                        ▼                                  │
                             ┌──────────────────┐               ┌──────────┴────────┐
                             │ D17LaunchFactory │               │ D17LockerFactory  │ settleAfterGraceBatch
                             └─┬──────┬───────┬─┘               └──────────┬────────┘ (≤ 8 lockers)
               deployToken     │      │       │ deployVault                │ createLockerFor
                               ▼      │       ▼                            ▼ (msg.sender == owner)
                 ┌───────────────┐    │   ┌─────────────────────────┐ ┌────────────┐
                 │D17TokenFactory│    │   │D17LiquidityVaultFactory │ │ D17Locker  │ personal escrow,
                 └──────┬────────┘    │   └───────────┬─────────────┘ └─────┬──────┘ positions across
                        ▼             ▼ deployLaunch  ▼                     │        launches
                 ┌───────────┐ ┌───────────────────┐ ┌───────────────────┐  │
                 │ D17Token  │ │ D17LaunchDeployer │ │ D17LiquidityVault │◄─┤ penalties,
                 └───────────┘ └─────────┬─────────┘ │ (LP locked,       │  │ pool-share WETH
                       ▲                 ▼           │  creator vesting, │  │
                       │           ┌───────────┐     │  failed-penalty   │  │
                       │ gate reads│ D17Launch │◄───►│  return)          │  │
                       │ tradingOpen└──────────┘◄──┐ └───────────────────┘  │
                       └────────────────┘          └─────────────────────────┘ onlyLocker
          vault → launch (onlyVault): claimVaultLiquidityTokens, markLiquidityPoolCreated
          launch → vault (launch only): returnFailedPenalty

Authority edges (all others are permissionless or view):

D17LockerFactory.settleAfterGraceBatch calls D17Locker.settleAfterGrace, which is permissionless anyway: the batch holds no authority of its own (§5.9). The vault's mintLateLiquidity keeps a registered-locker check but always reverts (D17LiquidityVault.sol:172-175).

Canonical registry: D17Factory.launches[launch] = LaunchRecord{canonical, creator, token, liquidityVault, rulesHash} written once at creation (D17Factory.sol:184-190); isCanonicalLaunch(launch, rulesHash) requires both the address and the pinned rules hash to match (D17Factory.sol:206-209). Lockers never trust an address alone.

#3. Deployment & wiring

Suite deployment (per scripts/deploy-factory.mjs): deploy D17FeeConfig(feeOwner, feeRecipient, feeBps) (optionally preceded by an ownerless D17FeeSplitter used as feeRecipient), D17Factory(owner, weth, router, feeConfig), D17TokenFactory(owner), D17LiquidityVaultFactory(owner), D17LaunchDeployer(owner), D17LaunchFactory(d17Factory, tokenFactory, vaultFactory, launchDeployer), D17LockerFactory(d17Factory); pin the launch factory into the token factory, vault factory, launch deployer and D17Factory, pin the locker factory into D17Factory; renounce every owner, and the fee config's too when RENOUNCE_FEE_CONFIG_OWNER=1. Every pin is one-shot (D17Factory.sol:125-141; D17TokenFactory.sol:28-35; D17LiquidityVaultFactory.sol:28-35; D17LaunchDeployer.sol:32-39). renounceOwnership requires the pins first (D17Factory.sol:149-154; D17LaunchDeployer.sol:41-45).

Renunciation is enforced, not advisory: createLaunch reverts with FACTORY_NOT_RENOUNCED while D17Factory has an owner (D17Factory.sol:167) and deployLaunch reverts with FACTORIES_NOT_RENOUNCED while the token factory, vault factory or launch deployer has one (D17LaunchFactory.sol:95-100). On Ethereum mainnet (block.chainid == 1) createLaunch also reverts with MAINNET_FEE_NOT_FROZEN while the fee config has an owner or a pending owner (D17Factory.sol:173-179), so the fee rate and recipient are final for the whole mainnet suite. The deploy script refuses to run without RENOUNCE_D17_FACTORY_OWNER=1 and, on mainnet, without RENOUNCE_FEE_CONFIG_OWNER=1; verify:factory checks every owner is zero.

Launch creation is one transaction, D17Factory.createLaunch(config) (D17Factory.sol:160-204) → D17LaunchFactory.deployLaunch(config, msg.sender, feeRecipient, feeBps):

rulesHash() is read after vault configuration (it includes liquidityVault), so the registered hash is final (D17Factory.sol:183; D17Launch.sol:275-305).

#4. Lifecycle state machine

Contract rounds 0–4 = display rounds 1–5. Timing anchors: startTime (immutable), roundStart/roundEnd (derived walk over roundSeconds[5] + refundSeconds after rounds 0–3, D17Launch.sol:326-338), tradingOpenAt = roundEnd(4) + settlementSeconds (immutable, D17Launch.sol:243), finalizedAt (set at finalization), poolCreationOpensAt() = finalized ? max(finalizedAt + settlementSeconds, tradingOpenAt) : tradingOpenAt (D17Launch.sol:423-427). tradingOpen() == liquidityPoolCreated (D17Launch.sol:429-431). On Ethereum mainnet (block.chainid == 1) the factory requires startTime ≥ now + 1 day and every round/refund/settlement window ≥ 1 hour (D17Factory.sol:234-243, 255).

launchPhase() (D17Launch.sol:522-554) reports one of 8 phases:

Failure is terminal-by-predicate (only reachable pre-finalization); finalization is one-shot (FINALIZED, D17Launch.sol:769) and requires nonzero committed WETH (:779). Pool creation is one-shot (POOL_CREATED + VAULT_LIQUIDITY_CLAIMED, D17Launch.sol:704-705; vault poolCreated, D17LiquidityVault.sol:124) and requires every final commitment to be settled (UNSETTLED_COMMITMENTS, D17Launch.sol:707). The V15 late path is gone: claimLateSettlement reverts LATE_SETTLEMENT_DISABLED (D17Launch.sol:655-657) and so does the vault's mintLateLiquidity (D17LiquidityVault.sol:172-175).

#5. Per-contract reference

Notation: AC = access control. All state-changing functions in D17Launch, D17Locker, D17LiquidityVault are nonReentrant (storage-flag pattern, e.g. D17Launch.sol:192-197); not repeated per row. receive()/fallback() revert on D17Launch (:258-264), D17Locker (:89-95), D17LiquidityVault (:98-104).

#5.1 D17Factory (D17Factory.sol, 344 lines)

Purpose: entry point, config validation, fee snapshot, canonical launch + locker registries. Constants: D17_FACTORY_ID (:18), BPS = 10_000 (:19), MAX_TREASURY_BPS = 1_000 (:22), MAX_MANUAL_DISTRIBUTION_BPS = 1_000 (:23), MIN_REFUND_PENALTY_BPS = 100 / MAX_REFUND_PENALTY_BPS = 2_500 (:26-27), ROUND_COUNT = 5 (:28), metadata bounds (:29-34), MIN_COMMIT_WETH = 1e15 (:35), MIN_LP_TOKENS = 1e18 (:36), MIN_ROUND_ALLOCATION_TOKENS = 1e18 (:37), MAX_TOKEN_SUPPLY = type(uint112).max (:39, Uniswap V2 reserve limit), MIN_ANCHOR_PRICE_WAD = 1e6 (:40), round-seconds bounds 60s–90d (:41-42), refund/settlement ≤ 30d (:43-44), MAX_START_DELAY = 365 days (:45), mainnet floors MAINNET_MIN_WINDOW_SECONDS = 1 hours / MAINNET_MIN_START_DELAY = 1 days (:49-50). Key storage: owner, immutable weth/router/feeConfig (:52-55), launchFactory/lockerFactory + pinned flags (:56-59), launches, isLocker, lockersByOwner (:69-71).

_validateConfig (:211-265) enforces: name/symbol length + JSON-safety; metadata bounds (description ≤ 512B, ≤ 8 links, link type [a-z0-9-] ≤ 32B, link URL https + ≤ 128B + JSON-safe, logo ≤ 8192B base64-SVG data URI, :267-304; the web app stops at 4096B so the creation fits the 16,777,216 gas cap per transaction); tokenSupply > 0; tokenSupply ≤ MAX_TOKEN_SUPPLY (SUPPLY_ABOVE_V2_RESERVE, :218); saleTokens > 0; lpTokens ≥ 1e18; saleTokens + lpTokens + manualDistributionTokens + deadTokens == tokenSupply (SUPPLY_SPLIT, :221-225); manualDistributionTokens * BPS ≤ tokenSupply * 1000 (MANUAL_ABOVE_CAP, :226-229); canonical dead recipient when deadTokens > 0 (:230-232); treasury nonzero (:233); startTime in [now (+1 day on mainnet), now + 365d] (START_TOO_SOON/START_TOO_FAR, :237-238); refund/settlement seconds in [1 (1h on mainnet), 30d] (:239-243); minCommitWeth ≥ 1e15; minPhase1Weth ≥ minCommitWeth; minAnchorPriceWad ≥ 1e6 (:244-246); treasuryBps ≤ 1000 (:247); 100 ≤ refundPenaltyBps ≤ 2500 (:248-251); 5 rounds, each 60s (1h on mainnet)–90d, each share

0 with allocation ≥ 1e18 tokens, shares summing to exactly 10 000 bps (:253-264). The manual-allocation recipient is not a config field - it is always msg.sender of createLaunch, passed as creator (:182). The config field maxProtocolFeeBps is the creator's consent bound (ID17LaunchFactory.sol).

Events: LaunchCreated(creator idx, launch idx, token idx, liquidityVault, rulesHash) (:74-80), ManualDistributionConfigured(launch idx, recipient idx, amount) (:89, emitted for every launch incl. amount 0), LaunchMetadataPublished(launch idx, metadataHash idx, description, logoSvgUri, linkTypes[], linkUrls[]) (:81-88), LockerRegistered(owner idx, locker idx, manager idx) (:90), pin/ownership events (:73, :91-92).

#5.2 D17FeeConfig (D17FeeConfig.sol, 74 lines)

Purpose: protocol fee settings for future launches. Constants: D17_FEE_CONFIG_ID (:17), MAX_PROTOCOL_FEE_BPS = 200 (:18). Storage: owner, pendingOwner, feeRecipient, protocolFeeBps (:20-23).

The fee config holds no funds and is never called by a launch: changing it cannot affect any existing launch (§7). On mainnet D17Factory.createLaunch also reads its owner() and pendingOwner() and requires both to be zero (D17Factory.sol:173-179), so a mainnet suite only ever runs with renounced, final fee settings. Events: ProtocolFeeUpdated(feeRecipient idx, protocolFeeBps), OwnershipTransferStarted, OwnershipTransferred (D17FeeConfig.sol:25-27).

#5.2b D17FeeSplitter (D17FeeSplitter.sol, 94 lines)

Purpose: optional feeRecipient that splits the protocol fee between fixed recipients. No owner, no setter. Constants: D17_FEE_SPLITTER_ID (:19), BPS = 10_000 (:20), MAX_RECIPIENTS = 5 (:21). Storage: weth (immutable), recipients and shares (set once), a reentrancy flag (:23-26).

Fees arrive as plain WETH transfers (D17Locker pays the launch's protocolFeeRecipient), so a splitter never runs code on receipt and can never block a settlement. Event: Distributed(token idx, recipient idx, amount) (:28). Covered by test/fee-splitter-e2e.mjs (a real launch's 1% fee split 50/25/25) and by the callback probes of test/adversarial-callbacks.mjs.

#5.3 D17LaunchFactory (D17LaunchFactory.sol, 177 lines) and D17LaunchDeployer (61 lines)

D17LaunchFactory is the atomic deployer of the token/launch/vault trio (§3). Immutables: d17Factory, tokenFactory, liquidityVaultFactory, launchDeployer (:58-61); constant CANONICAL_DEAD_RECIPIENT (:56).

_metadataHash(config) = keccak256(abi.encode(tokenName, tokenSymbol, description, logoSvgUri, links)) (:166-176).

D17LaunchDeployer exists only for code size: it holds D17Launch's creation code so the launch factory does not. deployLaunch(bytes encodedParams) (D17LaunchDeployer.sol:51-61) requires the pinned launch factory as caller, checks that the second static word of the encoded LaunchParams (the vault configurator) equals the caller, then creates D17Launch with creationCode ‖ encodedParams. Same owner → pin → renounce lifecycle as the other factories (:32-45). Code size (V15.1, release/protocol-build.json): D17LaunchDeployer 22,910 bytes (limit 24,576), so D17Launch creation code can grow by ~1.6 KB at most; D17Launch 17,722 bytes; D17Factory 11,538 bytes; D17LaunchFactory 5,129 bytes.

#5.4 D17Launch (D17Launch.sol, 847 lines) - the engine

Constants: D17_LAUNCH_ID (:10), FAILED_REFUND_POLICY = keccak256("D17_FAILED_R1_FULL_REFUND_V1") (:11), ROUND_COUNT = 5/FINAL_ROUND = 4/ REFUND_STAGE_COUNT = 4 (:12-14), EARLY_REFUND_ROUNDS = 2 (:17), EARLY_REFUND_PENALTY_BPS = 100 (:21), NO_ROUND (:22), phase constants (:23-30), BPS = 10_000 (:31), mins (:32-35), WAD = 1e18 (private, :36), dead address (:37). Immutables (:39-62): factory, vaultConfigurator, token, weth, treasury, protocolFeeRecipient, startTime, refundSeconds, settlementSeconds, tradingOpenAt, minCommitWeth, minPhase1Weth, minAnchorPriceWad, treasuryBps, protocolFeeBps, refundPenaltyBps, saleTokens, lpTokens, deadTokens, deadRecipient, manualDistributionTokens, manualDistributionRecipient, metadataHash. Constructor takes one LaunchParams struct (:113-138, :202-256); it keeps structural checks (incl. treasuryBps + protocolFeeBps < BPS and a fee recipient when the fee is nonzero, :208-209) while economic caps live in D17Factory.

Key storage (:64-102): liquidityVault (one-shot), liquidityPoolCreated, vaultLiquidityClaimed, officialPair, exactCommittedLiquidityWeth (:70, the exact sum of every locker's current pool share, maintained on each commitment and refund), settledLiquidityWeth (vault deliveries at settlement), finalCommittedWeth (finalization snapshot), settledCommittedWeth (gross settled), poolSettledLiquidityWeth/poolSettledCommittedWeth (pool-creation snapshots), lateSettledCommittedWeth/lateSettledLiquidityWeth/lateLpTokensReleased (:76-78, V15 fields kept for ABI compatibility; always zero in V15.1), vaultLiquidityTokensClaimed, write-once pool records (:80-83), roundSeconds[5]/roundSharesBps[5]/roundRaised[5] (:85-87), retainedPenaltyWeth/penaltyWethPaid/penaltyWethRefunded/ failedPenaltyWethRefunded[locker]/treasuryWethPaid/protocolFeeWethPaid (:89-94), unsoldSaleTokensSettled/unusedLpTokensBurned/effectiveLpTokens/ finalRoundTokenPool/unsoldSaleTokensBurned (:95-99), finalizedAt, finalized (:100-101). Per-locker Position{finalSaleTokensClaimed, liquidityClaimed, refundWeth, penaltyWeth, paid[5], refunded[5]} (private mapping, :104-111, :140).

State-changing ABI:

_settlePosition() (:659-691): requires vault configured, lazily finalizes (:668-669); requires position unclaimed (:672-673); computes sale tokens via previewFinalSaleTokens(msg.sender) and the WETH split via _vaultSettlementAmounts; requires gross > 0 (:677); sets both claim flags before transfers (:679-680); updates settledCommittedWeth, treasuryWethPaid, protocolFeeWethPaid and settledLiquidityWeth += wethForVault (:681-685); emits VaultSettlementClaimed (:686-688); finally transfers sale tokens to the calling locker (:690). The WETH itself never passes through the launch - the locker transfers it (see §5.5).

View ABI (selected; full signatures at cited lines): rulesHash() → bytes32 (:275 - abi.encode of the 27 fields at :277-303, first field D17_LAUNCH_ID, includes protocolFeeRecipient and protocolFeeBps, last field FAILED_REFUND_POLICY); activeRound() → uint8 (:307); activeRefundWindow() → uint8 (:318); roundStart/roundEnd/roundClaimTime(uint8) (:326/:336/:353); roundBaseTokenAllocation/roundTokenAllocation/roundSoldTokens(uint8) (:340/:345/:388); anchorPriceWad() (:359); anchorReady() (:365); launchFailed() (:369); roundAnchorTargetWeth/roundAnchorUnderfillRemainingWeth(uint8) (:376/:382 - defined for the final round too); rolloverToFinalRound() (:401); roundDiscoveredPriceWad(uint8) (:409); isRoundClaimable(uint8) (:415); settlementStartsAt() (:419); poolCreationOpensAt() (:423); tradingOpen() (:429); totalCommittedWeth() (:433); liquidityBps() (:438, informational: the pool no longer uses it); totalLiquidityWeth() (:445, exactCommittedLiquidityWeth + retainedPenaltyWeth); poolTokenAllocation() (:453); allFinalCommitmentsSettled() (:460 - gates pool creation and burnResidualTokens); contributedBy(address,uint8) (:464); lockerPositionState(address) (:469); previewRoundTokens(address,uint8) (:490); previewFinalSaleTokens(address) (:499); previewVaultSettlement(address) → (saleTokens, gross, wethForVault, treasuryWeth, protocolFeeWeth) (:505); launchPhase() (:522); public getters exactCommittedLiquidityWeth, penaltyWethRefunded, failedPenaltyWethRefunded(address). The V14 previewSettlement alias was removed.

Events (:142-180): LiquidityVaultConfigured, RoundCommitted(locker idx, round idx, amount), RoundRefunded(locker idx, refundRound idx, refundWeth, penaltyWeth), LaunchFailedRefunded(locker idx, refundWeth) (refundWeth includes returned penalties), FailedPenaltyRefunded(locker idx, penaltyWeth), VaultSettlementClaimed(locker idx, saleTokens, wethForVault, treasuryWeth, protocolFeeWeth, grossCommittedWeth), Finalized(finalizedAt), VaultLiquidityTokensClaimed(liquidityVault idx, liquidityTokens, wethForPool), LiquidityPoolCreated(liquidityVault idx, pair idx, tokenUsed, wethUsed, lpMinted), UnsoldSaleTokensBurned(amount), UnusedLpTokensBurned(amount), ResidualTokensBurned(amount), UnexpectedEthSwept(recipient idx, amount). LateVaultSettlementClaimed (:155-163) is still declared for ABI compatibility but is never emitted in V15.1. V14's UnsoldSaleTokensPaid no longer exists.

#5.5 D17Locker (D17Locker.sol, 337 lines) - per-user escrow

One locker per (user, deployment); registered in D17Factory; holds the user's WETH until refund/settlement and claimed sale tokens until withdrawal. EXPECTED_LAUNCH_ID (:10) pins the accepted launch version (D17_LAUNCH_V15_1). Immutables: owner, factory, weth (:13-15). Global ledgers: withdrawableWeth, accountedWeth (:17-18). Per-launch LockerPosition struct (:21-43); V15 inserted protocolFeeWeth after treasuryWeth (:34-35), shifting every later field of the public positions getter (:45) - decode it by field name. V15.1 adds failedPenaltyWethRefunded[launch] (:46). Every value-moving function updates the locker's ledgers before its external calls (checks-effects-interactions, V15.1).

_settleVaultPosition (:246-305): recomputes per-round previews locally (:251-259) and requires the launch-returned sale tokens to equal their sum (FINAL_CLAIM_MISMATCH, :267); calls claimVaultSettlement (:266), which reverts once the pool exists; requires wethCommitted ≥ wethForVault + treasuryWeth + protocolFeeWeth (:268-269); records the settlement and moves the leftover wethCommitted to the withdrawable residual (:271-287); then transfers wethForVault to the vault, treasuryWeth to the treasury and protocolFeeWeth to launch.protocolFeeRecipient() from the locker (:289-291). Emits VaultSettlementCompleted (:293-304).

#5.6 D17LiquidityVault (D17LiquidityVault.sol, 246 lines)

Purpose: creates and permanently holds the official LP position in one deposit, vests the creator allocation, returns failed-launch penalties. Constants: D17_LIQUIDITY_VAULT_ID (:13), CREATOR_VESTING_SECONDS = 180 days (:16), BURN_ADDRESS = 0x…dEaD (:17). Immutables: launch, token, weth, router, routerFactory, treasury (:19-24). Storage (:26-42): pool records, poolCreatedAt, creatorTokensReleased, pre-seed records, failedLaunchPenaltyWethRefunded (:38); the V15 fields lateTokenUsedForLp, lateWethUsedForLp, lateLpMinted, lateTokensBurned, lateWethBurned and failedLaunchPenaltyWethBurned (:32-37) stay in the ABI and are always zero. No function transfers or burns vault-held LP - LP is locked forever (recovery excludes it, :221).

Events (:44-66): OfficialPoolCreated(pair idx, tokenUsed, wethUsed, lpMinted, preseededTokenReserve, preseededWethReserve), FailedLaunchPenaltyReturned(locker idx, amount), CreatorTokensReleased(recipient idx, amount), sweep/recovery events. LateLiquidityAdded and FailedLaunchPenaltiesBurned are still declared but never emitted in V15.1.

#5.7 D17Token (D17Token.sol, 295 lines)

Unchanged from V14 except its identity string. Minimal ERC-20 (18 decimals, :19) with launch-coupled transfer/burn gates and on-chain metadata (contractURI). Owner = launch factory only during deployment; renounced in the same transaction (§3 step 12).

Gate logic _transferAllowedBeforeOpen(from, to) (:231-241): before configuration → false; from == launch → true; from == liquidityVault && to == canonicalPair() → true; otherwise requires _launchTradingOpen() - a try/catch read of launch.tradingOpen() that fails closed (:243-249). The creator allocation sits in the vault, so it can only leave through vesting once the pool exists. unchecked arithmetic in transferFrom/burn/_transfer is guarded by preceding requires (:174-177, :189-192, :224-227).

#5.8 D17TokenFactory / D17LiquidityVaultFactory (51 lines each)

Identical pattern: owner pins launchFactory once (:28-35), renounceOwnership requires the pin (:37-41), deployToken (D17TokenFactory.sol:43-50) / deployVault (D17LiquidityVaultFactory.sol:43-50) callable only by the pinned launch factory. IDs at :7. Events at :13-15. Their owners must be zero before any launch (§3).

#5.9 D17LockerFactory (D17LockerFactory.sol, 62 lines)

Immutable d17Factory (:13); constants MAX_SETTLEMENT_BATCH = 4 (:17) and SETTLEMENT_CALL_GAS = 3_000_000 (:18). Events LockerCreated(owner idx, locker idx) and BatchSettlementResult(launch idx, locker idx, success) (:20-21).

The batch adds no authority: each locker re-runs its own checks (stored rules hash, finalization, grace boundary) and the sale tokens stay in that locker for its owner. D17Locker.settleAfterGrace remains callable directly if a settlement ever needs more gas than the stipend.

#5.10 lib/D17SafeTransfer (29 lines)

safeTransfer (:10), safeTransferFrom (:15), safeApprove (:20), safeBurn (:25): raw-call wrappers tolerating missing return values, reverting with typed errors (:5-8). Not fee-on-transfer-safe - acceptable because the only tokens touched are D17Token, canonical WETH, and the V2 pair.

#6. The math

Units: WETH/token amounts in wei (18 decimals); prices in WAD (1e18) as WETH-per-token; shares/fees in BPS (1e4). All divisions floor; fee floors round in favour of the pool, token floors round against the claimant.

6.1 Anchor discovery (round 0). anchorPriceWad = roundRaised[0] * 1e18 / roundBaseTokenAllocation(0) (D17Launch.sol:359-363); anchorReady = roundRaised[0] ≥ minPhase1Weth ∧ anchorPriceWad ≥ minAnchorPriceWad (:365-367). If the window after round 0 closes without anchorReady, launchFailed() becomes true permanently (:369-371).

6.2 Round targets, sales, rollover. roundBaseTokenAllocation(r) = saleTokens * roundSharesBps[r] / BPS (:340-343). For every round r ≥ 1 (V14: rounds 1–3 only): roundAnchorTargetWeth(r) = roundTokenAllocation(r) * anchorPriceWad / WAD (:376-380); roundSoldTokens(r) = raised ≥ target ? allocation : allocation * raised / target (:388-399). Overfill above target is allowed and raises the round's price; underfill in rounds 1–3 rolls into the final round, rolloverToFinalRound = Σ_{r=1..3} max(base(r) − sold(r), 0) (:401-407). The final round's allocation is base(4) + rollover (snapshotted as finalRoundTokenPool at finalization, :775) and it sells at most allocation * raised / target: no round sells below the anchor price; what the final round cannot sell is burned (§6.4). Buyer share: _roundTokensForBuyer(r, paid) = sold(r) * paid / roundRaised[r] (round 0 uses the base allocation) (:817-828).

6.3 Refunds. In window r (windows follow rounds 0–3 only, :318-324): penalty = gross * (r < 2 ? EARLY_REFUND_PENALTY_BPS(=100) : refundPenaltyBps) / BPS, refund = gross − penalty (:601-602). roundRaised[r] is decremented by the gross amount; retainedPenaltyWeth += penalty (:603). The locker sends the penalty WETH to the liquidity vault (D17Locker.sol:183). If the launch then succeeds, every penalty is paired into the initial pool (§6.6). If it fails (only round-0 penalties can exist at that point), each locker's refundFailedLaunch returns its remaining principal and the penalties it paid: the launch tracks them per locker (position.penaltyWeth, failedPenaltyWethRefunded, D17Launch.sol:628-635) and the vault pays them back with returnFailedPenalty (D17LiquidityVault.sol:195-204). Nothing is burned and no fee is charged. This policy is pinned in every launch's rulesHash as FAILED_REFUND_POLICY (D17Launch.sol:11, :303).

6.4 Finalization (:768-798): one-shot; snapshots finalRoundTokenPool and finalCommittedWeth (> 0, :775-779); sold = Σ roundSoldTokens (capped at saleTokens, :830-833); unsoldSaleTokensSettled = saleTokens − sold; effectiveLpTokens = lpTokens * sold / saleTokens, unusedLpTokensBurned = lpTokens − effectiveLpTokens (:781-784); both remainders are burned in one safeBurn (:788-790). No unsold token is ever transferred to anyone.

6.5 Settlement split (:804-815): gross = Σ position.paid[r]; treasuryWeth = gross * treasuryBps / BPS; protocolFeeWeth = gross * protocolFeeBps / BPS; wethForVault = gross − treasuryWeth − protocolFeeWeth (both fees floor per position; the pool takes the remainder). Sale tokens = previewFinalSaleTokens (§6.2). The same function, _positionLiquidityWeth (:800-802), maintains the exact ledger: on every commitment and refund the launch adds or removes the change of the locker's wethForVault (:567-571, :591-596), so at any time exactCommittedLiquidityWeth = Σ_lockers wethForVault(locker). Who settles and when (owner, third party, batch) never changes the amounts.

6.6 Pool funding. Let L = effectiveLpTokens, P = retainedPenaltyWeth and E = exactCommittedLiquidityWeth = Σ_i (g_i − ⌊g_i·treasuryBps/BPS⌋ − ⌊g_i·protocolFeeBps/BPS⌋) over every locker i with final gross g_i; all three are fixed after finalization. totalLiquidityWeth() = E + P (D17Launch.sol:445-447). The pool opens only when every final commitment has settled (settledCommittedWeth == finalCommittedWeth, :460-462, required at :707), at which point the vault holds exactly settledLiquidityWeth + P WETH and the launch checks settledLiquidityWeth == E (LIQUIDITY_ACCOUNTING, :708). The single initial deposit is weth = E + P paired with tokens = L (:713-714): every reserved LP token and every wei of pool share, in one mint, at the canonical launch ratio (E + P) / L. Because L scales with the share sold and E with what was paid, the opening price tracks the average sale price whatever the fill: E ≈ finalCommittedWeth × liquidityBps / BPS (the per-locker fee floors put it at or above that aggregate, by less than two wei per locker), so the price is about avgSalePrice × (liquidityBps / BPS) × (saleTokens / lpTokens) plus the penalty contribution, and equals the average price net of fees when the creator sets lpTokens == saleTokens (ignoring penalties). The saleTokens / lpTokens factor is fixed in the published rules.

V15 computed the pool total once on the aggregate (T = finalCommittedWeth × liquidityBps / BPS + P) and the tokens as L × weth / T; per-position fee floors could make the settled WETH exceed that aggregate by a few wei, so a pool funded by fully settled positions asked for more than L tokens and reverted forever. V15.1 removes the ratio entirely: the WETH is the exact ledger and the tokens are exactly L. There is no late top-up, no live-ratio deposit and no burn of unpairable value: nobody can settle after trading opens, so no contribution ever meets a moved market price.

6.7 Dust & recovery paths. Launch: per-position sale-token dust → burnResidualTokens() once the pool exists (every commitment is settled by then, :750-756); force-sent ETH → sweepUnexpectedEthToTreasury as WETH (:760-766). Locker: ETH → recoverNativeEth; WETH above accountedWeth → recoverExcessWeth. Vault: post-pool WETH donations → sweepExcessWethToTreasury; foreign tokens → recoverUnsupportedTokenToTreasury (D17-token donations to the vault are unrecoverable by design, and so is WETH donated to the vault of a failed launch: returnFailedPenalty only pays recorded penalties and the sweep needs a pool).

6.8 Creator vesting. vestedCreatorTokens() = manualDistributionTokens * min(now − poolCreatedAt, 180 days) / 180 days (0 before the pool exists, D17LiquidityVault.sol:111-117); releaseCreatorTokens pays the difference with creatorTokensReleased to the fixed recipient (:179-186). lockedCreatorTokens() (:107) is excluded from the vault's token-balance check at pool creation (:145-148), so creator tokens can never be paired into the pool or burned. If the launch fails the pool never exists and the allocation stays in the vault forever.

#7. Access control & authenticity

Compatibility constants (all keccak256 values fixed in deployed bytecode, all ending in V15_1; the first V15 suites used V15_HARDENED, which the web app still recognises when the published manifest says so): D17_FACTORY_ID (D17Factory.sol:18), D17_FEE_CONFIG_ID (D17FeeConfig.sol:17), D17_LAUNCH_DEPLOYER_ID (D17LaunchDeployer.sol:11), D17_LAUNCH_ID (D17Launch.sol:10), D17_TOKEN_ID (D17Token.sol:15), D17_TOKEN_FACTORY_ID (D17TokenFactory.sol:7), D17_LIQUIDITY_VAULT_ID (D17LiquidityVault.sol:13), D17_LIQUIDITY_VAULT_FACTORY_ID (D17LiquidityVaultFactory.sol:7), and D17Locker.EXPECTED_LAUNCH_ID (D17Locker.sol:10), which must equal the launch ID - lockers reject V14 and other incompatible launches with BAD_LAUNCH_ID in verifyLaunch. D17_FEE_SPLITTER_ID (D17FeeSplitter.sol:19) is D17_FEE_SPLITTER_V1. rulesHash() covers every economic parameter, including the protocol fee rate and recipient and the failed-refund policy, with the launch ID as its first field (D17Launch.sol:275-305); lockers pin the hash at commit (D17Locker.sol:150) and settleAfterGrace re-verifies against the stored hash (D17Locker.sol:240).

Protocol fee isolation. The fee is read once, at creation, from D17FeeConfig (D17Factory.sol:170), checked against the creator's maxProtocolFeeBps (:180) and stored in launch immutables that are part of rulesHash. No launch, locker or vault ever calls the fee config again; the fee owner has no path to an existing launch or to any funds. On mainnet there is no fee owner at all: createLaunch requires the fee config's owner and pendingOwner to be zero (:173-179).

Self-registration: createLockerFor requires msg.sender == lockerOwner (D17LockerFactory.sol:31); registration is restricted to the pinned locker factory (D17Factory.sol:114-123) - isLocker contains only canonical locker bytecode, which is the basis for onlyLocker on the launch and the NOT_D17_LOCKER check of returnFailedPenalty on the vault. The vault pays a failed-launch penalty only when its own launch calls it with an amount taken from that launch's per-locker record.

Deliberately permissionless entry points and why they are safe:

#8. Invariants (enforcement map)

#9. Event catalogue (indexer/UI contract)

V15 events kept in the ABI but never emitted by V15.1: LateVaultSettlementClaimed (launch), LateLiquidityAdded and FailedLaunchPenaltiesBurned (vault). Indexers may keep their decoders; they will see no such logs from a V15.1 suite.

Indexing rule (product-level): D17 pipelines ingest only the events above - never ERC-20 Transfer/Approval or pair Swap/Sync.

#10. Testing

npm run test:contracts runs every suite below except the fuzz.

• Local E2E (contracts/test/local-e2e.mjs, fixture test/fixtures/local-launch.json, 25/10/10/55 split): enforced renounce before any launch; a failed weak-anchor launch with a last-second 20 ETH round-0 refund (1% penalty into the vault), then the failed refund returning that penalty to its payer, burnFailedLaunchPenalties reverting and nothing sent to the burn address; metadata/config adversarial reverts; an 18-locker 5-round main launch with refunds in every window (exact penalty amounts, penalties land in the vault, treasury untouched); exact protocol-fee and treasury-fee accounting per locker; finalization burns (unsold + unused LP); pool creation refused with UNSETTLED_COMMITMENTS while lockers are absent, third-party settlement of the absent lockers with exact amounts, then pool creation with penalties paired in and no LP reserve left; residual-dust burn; creator vesting at 50% and 100%; a control launch with an under-filled final round. 517 assertions, 0 failures.
• Hardening suite (contracts/test/hardening-e2e.mjs): fee config cap/recipient/ owner/two-step handover; factory caps (treasury, penalty bounds, consent bound); fee snapshot unchanged after a fee change; zero-fee launch; final round priced at the anchor with the remainder burned; effective LP and canonical opening ratio; pool refused until a third party settles the absent locker; after a price drop, no repeated settlement and no WETH or token burned; residual burn gating; forced-ETH sweep as WETH. 51 assertions, 0 failures.
• Mainnet minimums (contracts/test/mainnet-floors-e2e.mjs, local simulation with chain id 1, Hardhat network mainnetSim): start 1 second short of 24 hours rejected and exactly 24 hours accepted; each of the five rounds, the refund window and the settlement window rejected at 59m59s; testnet-valid short durations rejected; launches refused while the fee config is not frozen; then a full launch at exactly the minimums (1-hour rounds and windows): no commitment during the notice, a refund in the last seconds of the window, finalization, settlement and pool creation one hour after finalization. 36 assertions, 0 failures.
• Fee splitter (contracts/test/fee-splitter-e2e.mjs): constructor bounds and a real launch's 1% fee split 50/25/25, odd amounts, plain ETH and other tokens. 25 assertions, 0 failures.
• V15.1 regressions (contracts/test/v15-1-regressions-e2e.mjs), each reproduced on V15 before its fix: odd-wei commitments and a refund, every position settled (owner and settleAfterGraceBatch with junk entries), then the pool opens with exactly the reserved LP tokens and the exact WETH ledger; a supply of exactly 2^112 − 1 opens its pool and one more wei is rejected (SUPPLY_ABOVE_V2_RESERVE). 17 assertions, 0 failures.
• Failed-refund remediation (contracts/test/failed-refund-remediation.mjs): a failed round 0 returns principal plus penalties to each payer (including lockers that had already taken everything back), a donation to the vault does not increase any claim, a control without penalties, a successful launch where penalties still reach the pool, and hostile-callback probes on the refund path; gas per refund recorded. 80 checks, 0 failures.
• Adversarial callbacks (contracts/test/adversarial-callbacks.mjs, hostile WETH fixture test/CallbackWETH.sol): reentry into the locker during deposit and settlement transfers, cross-function reentry, the splitter's distribute and distributeEth; all denied by the guards, with exact accounting after each attempt; pool creation with an unsynced and a synced WETH donation to a real pair. 32 checks, 0 failures.
• Minimum liquidity (contracts/test/minimum-liquidity.mjs): the smallest LP allocation (1 token) with the smallest round-0 share and commitment opens a real Uniswap V2 pool; one wei less is rejected (LP_TOO_LOW). 4 checks, 0 failures.
• Rounding reference model (contracts/test/rounding-reference-model.mjs): a wei-exact BigInt model (no EVM) of random commitments, refunds and failed-launch refunds, checking that the incrementally maintained ledger always equals every locker's pool share recomputed from scratch (200 campaigns × 100 lockers, 24,620 operations, 84,000 checks; the V15 aggregate formula differs from the exact ledger at 29,220 of the 32,000 steps).
• The four V15.1 review suites use the real Uniswap V2 bytecode from @uniswap/v2-core (test/release-fixture.mjs); the older suites use the mock router/pair in contracts/test/.
• Stateful fuzz (contracts/test/fuzz-invariants.mjs, npm run test:fuzz -w @d17/contracts, FUZZ_SEED / FUZZ_CAMPAIGNS): each campaign draws a random launch configuration within the factory bounds and plays a random lifecycle (mixed, dust and whale commits; refunds in every window; failed launches with full refunds; explicit or lazy finalization; owner and third-party settlements; pool creation refused while any position is unsettled; WETH donations and post-open price moves; residual burn; creator vesting). After every action it checks WETH conservation per position and through the vault, the launch token ledger, exact fees and penalties, the return of every failed-launch penalty, the anchor floor (to 1 WAD unit), no post-open liquidity loss and vesting bounds; any revert of a valid action is a liveness failure, and adversarial calls are probed for their expected reverts. V15.1 campaigns pass; the last full V15 run was 4 seeds × 8 campaigns, 82,030 invariant checks, 381 adversarial probes, 0 failures. Not part of npm test (≈15 min per 8 campaigns).
• Deployment dry run on a local node: deploy:factory → verify:factory → create:launch. The terminal's creator-vesting release button was exercised in a browser against a local node with Sepolia's chain id.
• Run everything with npm ci && npm test.
• Coverage gaps worth noting: the fuzz suite is seeded and not run in CI; no mainnet-fork tests (the mainnet minimums run on a local chain-id-1 simulation, with mock WETH and router); the V15.1 Sepolia suite (2026-11-10) has no complete success and failure launch evidence yet.

#11. Known limitations & review status

1. Not independently audited. Slither 0.11.6 reports only benign findings (reentrancy into own token/WETH/pair behind nonReentrant, intended timestamp comparisons, the intended pre-seed strict equality, default-zero locals, a missing zero check on the fee config's two-step handover where zero cancels a pending transfer).
2. Code-size ceiling: D17LaunchDeployer is 22,910/24,576 bytes; any growth of D17Launch consumes that margin. Check sizes after every source change.
3. AMM assumption: honest Uniswap-V2 semantics. The pool receives one balanced deposit before any trading, and no liquidity is added afterwards, so there is no late deposit to sandwich.
4. WETH assumption: canonical WETH9 - no fee-on-transfer, no hooks.
5. unchecked blocks: only in D17Token (:174-177, :189-192, :224-227), each guarded.
6. Config economics: the factory validates hard caps (treasury ≤ 10%, protocol fee ≤ 2%, rounds 3–4 penalty 1–25%, supply ≤ 2^112 − 1), not whether a launch is attractive. The contract accepts any LP allocation from 1 token, so a creator can set an opening price far above the average price paid.
7. Settlement gas before trading: every buyer must be settled before the pool can open. Someone (usually the creator) pays the gas to settle absent buyers, up to 4 per settleAfterGraceBatch; each position needs at least the launch's minimum commitment, which bounds the count.
8. Donation edge cases: post-open D17-token donations to the vault are stuck; WETH donated to the vault of a failed launch is stuck; the creator allocation of a failed launch is locked forever.
9. createLaunch gas: deploys three contracts in one transaction (~13–15M gas).
10. No admin recovery: launches are immutable once created; the only remedy for a bad suite is a new suite. A fee config owner (test networks only) can only change future fees.
11. Block timestamps: windows use block.timestamp; mainnet floors keep every window ≥ 1 hour so a few seconds of validator drift are immaterial.

Reference source: contracts/contracts/ and contracts/SHA256SUMS.txt.