@sentrix-labs/canonical-contracts 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to Sentrix canonical contracts are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Tag pattern `vX.Y.Z`. Each release tag corresponds to a coordinated deploy to mainnet (chain 7119) + testnet (chain 7120).
+
+---
+
+## [Unreleased]
+
+### Documentation
+
+- **`docs/ADDRESSES.md`** — added "SentrixSafe ownership" section documenting the 2026-04-28 migration history and the final 1-of-1 state.
+- **`script/TransferOwnership.s.sol`** — rewritten to document the completed migration with `AUTHORITY` / `SAFE_MAINNET` / `SAFE_TESTNET` constants. Read-only print of final state.
+- **`README.md`** — SentrixSafe row links to the ownership section in `docs/ADDRESSES.md`.
+
+### Governance
+
+- **SentrixSafe ownership migration FINAL (2026-04-28)** — both Safes now 1-of-1 with the Sentrix Labs authority signer `0xa25236925bc10954e0519731cc7ba97f4bb5714b` (threshold=1). Bootstrap deployer retired from Safe ownership.
+
+  | Step | Chain | Tx | Block |
+  |---|---|---|---|
+  | addOwner(authority, 1) | testnet 7120 | `0xb70a83eb416e…` | 881639 |
+  | addOwner(authority, 1) | mainnet 7119 | `0xd17400c35f07…` | 755821 |
+  | removeOwner(deployer, 1) | testnet 7120 | `0xb0c69e89252c…` | 884599 |
+  | removeOwner(deployer, 1) | mainnet 7119 | `0x8e9ca8b4cbe0…` | 757829 |
+
+---
+
+## [1.0.0] — 2026-04-27 — Initial deploy to Sentrix mainnet (7119) + testnet (7120)
+
+> **All four canonical contracts deployed.** Single coordinated deploy session by `0x5acb04058fc4dfa258f29ce318282377cac176fd` (bootstrap deployer EOA, retired from Safe ownership 2026-04-28). All addresses immutable.
+
+### Deployed — chain 7119 (Sentrix mainnet)
+
+| Contract | Address | Block | Deploy tx |
+|---|---|---|---|
+| WSRX | `0x4693b113e523A196d9579333c4ab8358e2656553` | 716787 | `0xc5b5016338ba2de65ebb631374724bcc33db63b9a570e77d455d896b40f103fb` |
+| Multicall3 | `0xFd4b34b5763f54a580a0d9f7997A2A993ef9ceE9` | 717078 | `0x64633e100f952d845970590fda32786118cf5e6b29b56c281d8d1e4b8e889f0a` |
+| TokenFactory | `0xc753199b723649ab92c6db8A45F158921CFDEe49` | 717392 | `0xfda6219d60219e223d049158bca734d77e475c0b6b0c02074beeba0c701be112` |
+| SentrixSafe | `0x6272dC0C842F05542f9fF7B5443E93C0642a3b26` | 717618 | `0xc67fb31dd135051732a41530e26897fb7c10eaec1fc6cb9334b596073758cb0f` |
+
+### Deployed — chain 7120 (Sentrix testnet)
+
+| Contract | Address | Block | Deploy tx |
+|---|---|---|---|
+| WSRX | `0x85d5E7694AF31C2Edd0a7e66b7c6c92C59fF949A` | 723183 | `0xfcfd2e0c1b3b4e61a2166a35cbb780d8370e9d1d6c67f7137aeb66c52260e8b3` |
+| Multicall3 | `0x7900826De548425c6BE56caEbD4760AB0155Cd54` | 723191 | `0x1f8d6749f7ffdcbbaabfad21167d5133593944be6c59025c69c3f6543cb7f6c2` |
+| TokenFactory | `0x7A2992af0d4979aDD076347666023d66d29276Fc` | 723195 | `0xe68e5553af080a97181e09279782873f884477759656e51c03f522c94cb9da47` |
+| SentrixSafe | `0xc9D7a61D7C2F428F6A055916488041fD00532110` | 723511 | `0x514863050498a545fa627d696aa82cdd2558bc35470418d7f83af8f1c0a12176` |
+
+### Initial scaffold (pre-deploy work, all merged)
+
+- `contracts/WSRX.sol` — Wrapped SRX (ERC-20, 18-decimal, native bridge)
+- `contracts/Multicall3.sol` — Standard Multicall3 (read/write batch)
+- `contracts/SentrixSafe.sol` — Minimal multi-sig (Gnosis Safe v1.4.1-derived; array-based owners with `addOwner` / `removeOwner` / `execTransaction`)
+- `contracts/TokenFactory.sol` — ERC-20 deployer (open factory, anyone may call)
+- `script/Deploy*.s.sol` — Foundry deploy scripts (per-contract) + `CheckDeployment.s.sol` smoke test
+- `test/*.t.sol` — unit + fuzz + invariant + integration tests
+- `deployments/{7119,7120}.json` — populated with deployed addresses
+- `deployments/abi/*.json` — ABI exports refreshed via `script/copy-abi.sh`
+- `docs/ADDRESSES.md` — auto-generated from deployments JSON via `script/GenerateAddressDocs.sh`
+- CI: `forge build + test + snapshot`, slither static analysis, CodeQL — all green
+
+### Notes
+
+- WSRX, Multicall3, and TokenFactory have **no owner role** (immutable). Only SentrixSafe has owner-set governance via `execTransaction`.
+- SentrixSafe deployed initially as a **1-of-1 multisig owned by the bootstrap deployer**. Migrated to 1-of-1 with authority signer post-deploy (see Unreleased §Governance above).
+
+Multicall3 deployed at a non-canonical address — the cross-chain canonical `0xcA11bde05977b3631167028862bE2a173976CA11` (via Create2 deployer) is **not** in use here. Initial Sentrix deploy used plain CREATE for v1; future revisions may add a Create2 path if cross-chain tooling demands it.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sentrix Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,19 @@
+Sentrix Canonical Contracts
+Copyright 2026 Sentrix Labs
+
+This product includes software developed by Sentrix Labs, distributed under
+the Business Source License 1.1 (BUSL-1.1) — see LICENSE.
+
+Change Date: 2030-01-01
+On the Change Date, the License terms convert to the Apache License,
+Version 2.0, as published by the Apache Software Foundation.
+
+This product mirrors third-party software:
+  - contracts/Multicall3.sol — verbatim from github.com/mds1/multicall
+    (MIT License, copyright Matt Solomon). License preserved in the
+    file's SPDX header.
+
+Trademark notice: SENTRIX and SENTRIX CHAIN are trademarks of Sentrix
+Labs. Use of these marks in the unmodified canonical contracts is
+permitted under the BUSL-1.1 use grant. Use of the marks in derivative
+works requires written permission.

package/README.md

@@ -0,0 +1,150 @@
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/sentrix-labs/brand-kit@master/png-transparent/sentrix-labs-256.png" alt="Sentrix Labs" width="120">
+</p>
+
+<h1 align="center">Sentrix Canonical Contracts</h1>
+
+<p align="center"><strong>Production EVM contracts for <a href="https://sentrixchain.com">Sentrix Chain</a> — WSRX, Multicall3, SentrixSafe, TokenFactory.</strong></p>
+
+<p align="center">
+  <a href="https://github.com/sentrix-labs/canonical-contracts/actions/workflows/ci.yml"><img src="https://github.com/sentrix-labs/canonical-contracts/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/sentrix-labs/canonical-contracts/actions/workflows/security.yml"><img src="https://github.com/sentrix-labs/canonical-contracts/actions/workflows/security.yml/badge.svg" alt="Security"></a>
+  <img src="https://img.shields.io/badge/license-BUSL--1.1-black" alt="License">
+  <img src="https://img.shields.io/badge/solc-0.8.24-blue" alt="Solidity">
+  <img src="https://img.shields.io/badge/foundry-stable-orange" alt="Foundry">
+</p>
+
+---
+
+## What's in here
+
+### Deployed on both chains (mainnet 7119 + testnet 7120)
+
+| Contract | Purpose |
+|---|---|
+| [`WSRX`](contracts/WSRX.sol) | Wrapped SRX — ERC-20 (18 decimals) backed 1:1 by native SRX. Lets EVM dApps hold SRX as a token. |
+| [`Multicall3`](contracts/Multicall3.sol) | Standard Multicall3 ([mds1/multicall](https://github.com/mds1/multicall)) for batched read/write calls. |
+| [`SentrixSafe`](contracts/SentrixSafe.sol) | Minimal multi-sig wallet (Gnosis Safe v1.4.1-derived) for treasury management. Currently configured 1-of-1 with the Sentrix Labs authority signer (`0xa25236925bc10954e0519731cc7ba97f4bb5714b`) on both chains — see [`docs/ADDRESSES.md`](docs/ADDRESSES.md#sentrixsafe-ownership). |
+| [`TokenFactory`](contracts/TokenFactory.sol) | Deploys minimal ERC-20 tokens via a single function call. v1 + v1.1.0 both deployed (see addresses doc). |
+
+### Deployed on mainnet (7119) only
+
+| Contract | Purpose |
+|---|---|
+| [`CoinBlastCurve`](contracts/CoinBlastCurve.sol) | Bonding-curve token contract. The CBLAST genesis token launched via this curve on 2026-05-01 — first on-chain CoinBlast bonding-curve launch. |
+
+### In-tree but not yet deployed
+
+| Contract | Purpose |
+|---|---|
+| [`CoinBlastFactory`](contracts/CoinBlastFactory.sol) | Launchpad-style factory that spawns new `CoinBlastCurve` instances. Code-complete; deployment gated on the launchpad UX surface landing. |
+| [`MerkleAirdrop`](contracts/MerkleAirdrop.sol) | Merkle-root airdrop distribution contract for the planned eligibility-based SRX drops. Code-complete; deployment gated on the airdrop campaign go-signal. |
+| [`StrategicReserveTimelock`](contracts/StrategicReserveTimelock.sol) | Time-locked treasury vault for the Strategic Reserve allocation. Code-complete; deployment gated on Strategic Reserve EOA → contract migration plan. |
+
+See [`docs/ADDRESSES.md`](docs/ADDRESSES.md) for deployed addresses on each chain.
+
+## Quickstart
+
+```bash
+git clone --recurse-submodules https://github.com/sentrix-labs/canonical-contracts.git
+cd canonical-contracts
+
+# Install Foundry: https://getfoundry.sh
+curl -L https://foundry.paradigm.xyz | bash && foundryup
+
+# Install dependencies
+make install
+
+# Build + test
+make build
+make test
+
+# Coverage
+make coverage     # outputs coverage/lcov.info
+```
+
+## Integrate
+
+```bash
+npm install @sentrix-labs/canonical-contracts ethers
+```
+
+```ts
+import { ethers } from "ethers";
+import abi from "@sentrix-labs/canonical-contracts/deployments/abi/WSRX.json";
+import deployments from "@sentrix-labs/canonical-contracts/deployments/7119.json";
+
+const provider = new ethers.JsonRpcProvider("https://rpc.sentrixchain.com");
+const wsrx = new ethers.Contract(deployments.WSRX.address, abi.abi, provider);
+console.log("totalSupply:", await wsrx.totalSupply());
+```
+
+Full integration guide → [`docs/INTEGRATION.md`](docs/INTEGRATION.md).
+
+## Deploy
+
+End-to-end runbook: [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md). High-level flow:
+
+```bash
+cp .env.example .env
+$EDITOR .env
+
+forge script script/DeployWSRX.s.sol --rpc-url sentrix_testnet --broadcast --private-key $DEPLOYER_PRIVATE_KEY
+forge script script/DeployWSRX.s.sol --rpc-url sentrix_mainnet --broadcast --private-key $DEPLOYER_PRIVATE_KEY
+
+# Update deployments/7119.json + 7120.json + CHANGELOG.md
+# Tag release
+git tag v1.0.0 && git push --tags
+```
+
+CI auto-creates a GitHub Release from the CHANGELOG entry.
+
+## Verify
+
+Sourcify-equivalent verification is on the ecosystem readiness Tier 1 backlog. Until that lands, run manual verification per [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) §12.
+
+Health-check a deployment:
+
+```bash
+WSRX_ADDR=0x... MULTICALL3_ADDR=0x... SAFE_ADDR=0x... FACTORY_ADDR=0x... \
+  forge script script/CheckDeployment.s.sol --rpc-url sentrix_testnet
+```
+
+## Security
+
+- All contracts immutable (no upgrade proxy — see [`docs/SECURITY_MODEL.md`](docs/SECURITY_MODEL.md))
+- Pre-merge: `forge test`, `forge build --sizes`, `slither`, `gitleaks`
+- Daily: scheduled slither + mythril runs ([`security.yml`](.github/workflows/security.yml))
+- Vulnerability disclosure: `security@sentrixchain.com` ([`SECURITY.md`](SECURITY.md))
+
+## Docs
+
+| Doc | What it covers |
+|---|---|
+| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Contract relationships + 8↔18 decimal conversion |
+| [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) | Step-by-step deploy runbook |
+| [`docs/INTEGRATION.md`](docs/INTEGRATION.md) | Code examples (ethers, wagmi) |
+| [`docs/SECURITY_MODEL.md`](docs/SECURITY_MODEL.md) | Trust assumptions + threat model |
+| [`docs/ADDRESSES.md`](docs/ADDRESSES.md) | Deployed addresses (auto-gen) |
+| [`docs/FAQ.md`](docs/FAQ.md) | Common questions |
+| [`docs/STORAGE_LAYOUT.md`](docs/STORAGE_LAYOUT.md) | Storage slots per contract |
+| [`docs/AUDIT.md`](docs/AUDIT.md) | Audit status + findings (when available) |
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md). PRs welcome — `forge test` + `forge fmt --check` + `slither --fail-high` must pass before merge.
+
+## Community
+
+- **GitHub Discussions** — https://github.com/sentrix-labs/canonical-contracts/discussions for integration questions, contract design feedback, deployment help.
+- **Org profile** — https://github.com/sentrix-labs
+
+## License
+
+BUSL-1.1 (see [`LICENSE`](LICENSE) + [`NOTICE`](NOTICE)). Change Date: 2030-01-01 → MIT.
+
+`Multicall3.sol` is a verbatim mirror of [mds1/multicall](https://github.com/mds1/multicall) (MIT) — license preserved in the file's SPDX header.
+
+---
+
+<p align="center"><sub>Built by <a href="https://github.com/sentrix-labs">Sentrix Labs</a> for <a href="https://sentrixchain.com">Sentrix Chain</a>.</sub></p>

package/contracts/CoinBlastCurve.sol

@@ -0,0 +1,369 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity 0.8.24;
+
+import {FactoryToken} from "./TokenFactory.sol";
+
+/// Minimal interface for the Sentrix V2 router/factory at graduation time.
+/// We use these only for read-only checks (audit H5 shadow-pair guard);
+/// the actual addLiquiditySRX call is still done via low-level call so the
+/// router ABI evolves independently.
+interface IRouterMinimal {
+    function factory() external view returns (address);
+}
+
+interface IFactoryMinimal {
+    function getPair(address tokenA, address tokenB) external view returns (address);
+}
+
+/// @title CoinBlastCurve
+/// @author Sentrix Labs
+/// @notice On-chain linear bonding curve for the CoinBlast launchpad. One
+///         instance per launched token. Buyers send native SRX, get tokens
+///         along the curve P(s) = P0 × (1 + K × s/S). When SRX raised hits
+///         the graduation threshold, anyone can call `graduate()` which
+///         seeds the canonical Sentrix V2 DEX pool with the raised SRX +
+///         remaining curve inventory and burns the resulting LP forever.
+///
+/// @dev Designed to match the frontend's bonding-curve.ts arithmetic
+///      exactly so off-chain estimates equal on-chain settlements.
+///
+///      Security model:
+///        - Immutable post-deploy: no admin keys, no upgrade path, no
+///          parameter mutation. Once SRX is raised it can only exit via
+///          a sell() back along the curve OR via graduate() into locked LP.
+///        - nonReentrant guards every state-changing entry point so the
+///          ERC-20 token's transfer hooks (or a malicious recipient on
+///          SRX refund) cannot re-enter the curve mid-trade.
+///        - On graduation, the launchpad calls into the DEX router and
+///          immediately burns the LP receipt — the raised SRX is locked
+///          as DEX liquidity forever.
+contract CoinBlastCurve {
+    // ── Immutable curve parameters ────────────────────────────────────
+    /// @notice ERC-20 token sold by this curve. The curve owns the entire
+    ///         initial supply at construction; tokens leave via buy() and
+    ///         return via sell()/graduate().
+    FactoryToken public immutable token;
+    /// @notice Total token supply (also the curve's denominator). Constant.
+    uint256 public immutable curveSupply;
+    /// @notice Base price numerator/denominator in SRX-wei per whole token.
+    ///         price0 = basePriceNum / basePriceDen (whole-token units).
+    uint256 public immutable basePriceNum;
+    uint256 public immutable basePriceDen;
+    /// @notice Curve steepness — k = kNum / kDen (e.g. 1/2 = 0.5).
+    uint256 public immutable kNum;
+    uint256 public immutable kDen;
+    /// @notice Once `srxRaised` reaches this value, graduation unlocks.
+    uint256 public immutable graduationSrxThreshold;
+    /// @notice Trading-fee taker (in basis points; capped at 500 = 5%).
+    address public immutable feeRecipient;
+    uint256 public immutable feeBps;
+    /// @notice Sentrix V2 router used for graduation. Pinned at construction
+    ///         so a future router upgrade can't redirect graduation flow.
+    address public immutable router;
+    /// @notice WSRX address — needed by router.addLiquiditySRX. Pinned.
+    address public immutable wsrx;
+
+    /// @dev Hard cap on fees so a misconfigured deploy can't drain users.
+    uint256 public constant MAX_FEE_BPS = 500; // 5%
+    /// @dev Bound on basePriceNum × kNum so the curve-cost product stays
+    ///      under 2^256 across the full supply range (see _curveCost notes).
+    uint256 public constant MAX_PRICE_NUM = 1e18;
+    uint256 public constant MAX_K_NUM = 1e3;
+    uint256 public constant MAX_CURVE_SUPPLY = 1e30; // 1T tokens × 1e18
+
+    // ── Mutable curve state ───────────────────────────────────────────
+    /// @notice Tokens currently held by buyers (= curveSupply - balanceOf(this)).
+    uint256 public tokensSold;
+    /// @notice Cumulative native SRX received (net of fees + sells).
+    uint256 public srxRaised;
+    /// @notice Latched true after graduate() runs. Locks buy/sell forever.
+    bool public graduated;
+
+    /// @dev Reentrancy lock — initialised to 1 so the first acquire is cheap.
+    uint256 private _locked = 1;
+
+    // ── Events ────────────────────────────────────────────────────────
+    event Buy(address indexed buyer, uint256 srxIn, uint256 fee, uint256 tokensOut);
+    event Sell(address indexed seller, uint256 tokensIn, uint256 fee, uint256 srxOut);
+    event Graduated(address indexed pair, uint256 srxLiquidity, uint256 tokenLiquidity, uint256 lpBurned);
+
+    // ── Errors ────────────────────────────────────────────────────────
+    error AlreadyGraduated();
+    error NotGraduatable();
+    error ZeroValue();
+    error Slippage();
+    error InsufficientReserve();
+    error TransferFailed();
+    error Reentrancy();
+    error FeeTooHigh();
+    error InvalidParams();
+
+    modifier nonReentrant() {
+        if (_locked != 1) revert Reentrancy();
+        _locked = 2;
+        _;
+        _locked = 1;
+    }
+
+    modifier active() {
+        if (graduated) revert AlreadyGraduated();
+        _;
+    }
+
+    /// @notice One-shot construction parameters — packed into a struct so the
+    ///         constructor stays under solc's stack-depth limit (12 args
+    ///         tripped the EVM-stack frame for the via-Yul codegen).
+    struct InitParams {
+        string name;
+        string symbol;
+        uint256 curveSupply;
+        uint256 basePriceNum;
+        uint256 basePriceDen;
+        uint256 kNum;
+        uint256 kDen;
+        uint256 graduationSrxThreshold;
+        address feeRecipient;
+        uint256 feeBps;
+        address router;
+        address wsrx;
+    }
+
+    // ── Construction ──────────────────────────────────────────────────
+    constructor(InitParams memory p) {
+        if (p.curveSupply == 0 || p.basePriceDen == 0 || p.kDen == 0) revert InvalidParams();
+        if (p.graduationSrxThreshold == 0) revert InvalidParams();
+        if (p.router == address(0) || p.wsrx == address(0) || p.feeRecipient == address(0)) revert InvalidParams();
+        if (p.feeBps > MAX_FEE_BPS) revert FeeTooHigh();
+        // Magnitude bounds — see _curveCost. Without these, the slope-term
+        // product can overflow uint256 for extreme parameter combinations.
+        if (p.basePriceNum > MAX_PRICE_NUM || p.kNum > MAX_K_NUM) revert InvalidParams();
+        if (p.curveSupply > MAX_CURVE_SUPPLY) revert InvalidParams();
+
+        token = new FactoryToken(p.name, p.symbol, p.curveSupply, address(this));
+        curveSupply = p.curveSupply;
+        basePriceNum = p.basePriceNum;
+        basePriceDen = p.basePriceDen;
+        kNum = p.kNum;
+        kDen = p.kDen;
+        graduationSrxThreshold = p.graduationSrxThreshold;
+        feeRecipient = p.feeRecipient;
+        feeBps = p.feeBps;
+        router = p.router;
+        wsrx = p.wsrx;
+    }
+
+    // ── Curve math ────────────────────────────────────────────────────
+    //
+    // Linear curve: P(s) = (basePriceNum / basePriceDen) × (1 + (kNum/kDen) × s / curveSupply)
+    //
+    // Cost to move from `a` tokens-sold to `b` tokens-sold (with b > a):
+    //   ∫[a,b] P(s) ds
+    //   = (basePriceNum / basePriceDen) × (b − a)                                 // base term
+    //     + (basePriceNum / basePriceDen) × (kNum / kDen) × (b² − a²) / (2 × curveSupply)  // slope term
+    //
+    // We multiply through to keep everything in SRX-wei and uint256-safe. With
+    // curveSupply ≤ 1e30 (1B tokens × 1e18), b² ≤ 1e60 still fits into uint256.
+
+    /// @notice SRX-wei cost to move from `a` to `b` tokens (b ≥ a, both in token-wei).
+    /// @dev    Linear bonding curve P(s) = P0 × (1 + K × s/S) integrates to:
+    ///           Cost = P0 × Δ + P0 × K × Δ × (a+b) / (2S)
+    ///         where Δ = b - a, S = curveSupply.
+    ///
+    ///         To avoid uint256 overflow on the slope term we apply the
+    ///         constructor-enforced bounds:
+    ///             basePriceNum ≤ 1e18, kNum ≤ 1e3, curveSupply ≤ 1e30
+    ///         The largest intermediate is `basePriceNum × kNum × delta × sum`
+    ///         which is ≤ 1e18 × 1e3 × 1e30 × 2e30 = 2e81 — ABOVE 2^256.
+    ///         So we factor and divide eagerly: compute `delta × sum / (2S)`
+    ///         first (≤ S = 1e30, safe), then multiply by `basePriceNum × kNum`
+    ///         (≤ 1e21), giving a final ≤ 1e51 → safe.
+    function _curveCost(uint256 a, uint256 b) internal view returns (uint256) {
+        if (b <= a) return 0;
+        uint256 delta = b - a;
+
+        // Base term: P0 × Δ
+        uint256 baseTerm = (basePriceNum * delta) / basePriceDen;
+
+        // Slope term in three steps with eager division to keep intermediates
+        // bounded:
+        //   step1 = (delta × (a + b)) / (2 × curveSupply)        ≤ curveSupply
+        //   step2 = step1 × basePriceNum × kNum                   ≤ 1e51
+        //   step3 = step2 / (basePriceDen × kDen)                 = result
+        //
+        // Two ordering caveats:
+        //   - delta × (a + b) can reach 2 × curveSupply² = 2 × 1e60. Still
+        //     under 2^256 (≈ 1.16e77), so the multiplication itself is safe.
+        //   - Eager division by (2 × curveSupply) discards up to (2S - 1)
+        //     wei of precision per term. Test suite asserts settlement
+        //     within ≤ 1 wei of the TS reference for typical params.
+        uint256 sum = a + b;
+        uint256 slopeTerm = (delta * sum) / (2 * curveSupply);
+        slopeTerm = slopeTerm * basePriceNum;
+        slopeTerm = (slopeTerm * kNum) / (basePriceDen * kDen);
+
+        return baseTerm + slopeTerm;
+    }
+
+    /// @notice Cost in SRX-wei for buying enough tokens to move from
+    ///         `tokensSold` → `tokensSold + tokensOut`. View helper.
+    function quoteBuy(uint256 tokensOut) public view returns (uint256 grossSrxIn, uint256 fee) {
+        if (tokensOut == 0) return (0, 0);
+        if (tokensSold + tokensOut > curveSupply) revert InsufficientReserve();
+        uint256 baseCost = _curveCost(tokensSold, tokensSold + tokensOut);
+        // Fee is taken on top of the curve cost so the user pays
+        // grossSrxIn = baseCost + fee.
+        fee = (baseCost * feeBps) / (10_000 - feeBps);
+        grossSrxIn = baseCost + fee;
+    }
+
+    /// @notice Tokens received when selling along the curve.
+    function quoteSell(uint256 tokensIn) public view returns (uint256 srxOut, uint256 fee) {
+        if (tokensIn == 0) return (0, 0);
+        if (tokensIn > tokensSold) revert InsufficientReserve();
+        uint256 baseRefund = _curveCost(tokensSold - tokensIn, tokensSold);
+        fee = (baseRefund * feeBps) / 10_000;
+        srxOut = baseRefund - fee;
+    }
+
+    // ── Trade entrypoints ─────────────────────────────────────────────
+
+    /// @notice Buy along the curve. Caller specifies `minTokensOut` for slippage
+    ///         protection. Excess SRX is refunded.
+    function buy(uint256 minTokensOut) external payable active nonReentrant returns (uint256 tokensOut) {
+        if (msg.value == 0) revert ZeroValue();
+
+        // Binary search for the largest tokensOut such that quoteBuy(tokensOut) ≤ msg.value.
+        // For a strictly-monotone-increasing curve this converges in ≤256 iterations.
+        uint256 lo = 0;
+        uint256 hi = curveSupply - tokensSold;
+        while (lo < hi) {
+            uint256 mid = lo + (hi - lo + 1) / 2;
+            (uint256 cost,) = quoteBuy(mid);
+            if (cost <= msg.value) lo = mid;
+            else hi = mid - 1;
+        }
+        tokensOut = lo;
+        if (tokensOut < minTokensOut) revert Slippage();
+        if (tokensOut == 0) revert ZeroValue();
+
+        (uint256 grossPaid, uint256 fee) = quoteBuy(tokensOut);
+
+        tokensSold += tokensOut;
+        srxRaised += (grossPaid - fee);
+
+        // Forward fee to recipient; refund any dust to buyer.
+        if (fee > 0) _safeSendSRX(feeRecipient, fee);
+        uint256 refund = msg.value - grossPaid;
+        if (refund > 0) _safeSendSRX(msg.sender, refund);
+
+        require(token.transfer(msg.sender, tokensOut), "CoinBlast: TOKEN_TRANSFER");
+
+        emit Buy(msg.sender, grossPaid, fee, tokensOut);
+    }
+
+    /// @notice Sell tokens back along the curve. Caller must have approved
+    ///         the curve for `tokensIn` beforehand.
+    function sell(uint256 tokensIn, uint256 minSrxOut)
+        external
+        active
+        nonReentrant
+        returns (uint256 srxOut)
+    {
+        if (tokensIn == 0) revert ZeroValue();
+        (uint256 srxNet, uint256 fee) = quoteSell(tokensIn);
+        if (srxNet < minSrxOut) revert Slippage();
+
+        require(token.transferFrom(msg.sender, address(this), tokensIn), "CoinBlast: TOKEN_TRANSFER_FROM");
+        tokensSold -= tokensIn;
+
+        // Audit H4 (HIGH, 2026-05-07): srxRaised is a derived figure that
+        // can drift from address(this).balance because quoteBuy/quoteSell fee
+        // math truncates sub-wei lossage on each trade. The pre-fix line was
+        // `srxRaised -= (srxNet + fee)` which could underflow → revert →
+        // sells permanently locked until graduation threshold met. Clamp the
+        // debit at zero so the underflow is impossible; address(this).balance
+        // remains the true source of truth for outflows below.
+        uint256 debit = srxNet + fee;
+        srxRaised = srxRaised >= debit ? srxRaised - debit : 0;
+
+        if (fee > 0) _safeSendSRX(feeRecipient, fee);
+        _safeSendSRX(msg.sender, srxNet);
+
+        emit Sell(msg.sender, tokensIn, fee, srxNet);
+        srxOut = srxNet;
+    }
+
+    // ── Graduation ────────────────────────────────────────────────────
+
+    /// @notice Anyone may trigger graduation once the SRX raised meets the
+    ///         threshold. Migrates raised SRX + remaining tokens into a fresh
+    ///         Sentrix V2 pool and burns the LP forever.
+    function graduate() external active nonReentrant {
+        if (srxRaised < graduationSrxThreshold) revert NotGraduatable();
+
+        // Audit H5 (HIGH, 2026-05-07): graduate() was unauthenticated and
+        // someone could front-run by pre-creating a (token, wsrx) pair on
+        // the V2 factory with skewed reserves before this call. addLiquidity
+        // would then mint LP at a manipulated ratio, leaking value to whoever
+        // arbitraged the first post-graduation swap. Guard: read the pinned
+        // router's factory, ask if a pair already exists for our (token, wsrx),
+        // and revert if so. This forces the curve to be the SOLE creator of
+        // its launch pair.
+        address factoryAddr = IRouterMinimal(router).factory();
+        require(
+            IFactoryMinimal(factoryAddr).getPair(address(token), wsrx) == address(0),
+            "CoinBlast: PAIR_EXISTS"
+        );
+
+        graduated = true;
+
+        uint256 tokenLiquidity = token.balanceOf(address(this));
+        // Surfaced during testnet smoke 2026-05-01: integer rounding inside
+        // quoteBuy/quoteSell can leave srxRaised a few wei *above* the
+        // actual native balance (the fee math discards sub-wei lossage on
+        // each trade, accumulated). Sourcing srxLiquidity from
+        // address(this).balance avoids router.call{value: srxLiquidity}
+        // reverting with insufficient-native-funds at the very last step.
+        // We still zero srxRaised so any future read sees 0 — the curve
+        // is graduated either way.
+        uint256 srxLiquidity = address(this).balance;
+        srxRaised = 0;
+
+        // Approve router to pull tokens, then add liquidity. LP receipt is
+        // sent to address(0) → permanently locked.
+        require(token.approve(router, tokenLiquidity), "CoinBlast: APPROVE");
+        (bool ok, bytes memory ret) = router.call{value: srxLiquidity}(
+            abi.encodeWithSignature(
+                "addLiquiditySRX(address,uint256,uint256,uint256,address,uint256)",
+                address(token),
+                tokenLiquidity,
+                tokenLiquidity, // accept any positive token amount (we control supply)
+                srxLiquidity,    // accept any positive SRX amount (we control raise)
+                address(0xdEaD),  // LP receipt destination — burnt forever
+                block.timestamp + 1 hours
+            )
+        );
+        require(ok, "CoinBlast: ADD_LIQUIDITY");
+        // ret = (uint amountToken, uint amountSRX, uint liquidity); we only
+        // need the LP amount for the event log.
+        (,, uint256 lpBurned) = abi.decode(ret, (uint256, uint256, uint256));
+
+        // Compute the pair address by re-using the factory we already
+        // looked up at the H5 guard above (no need for two factory() calls).
+        address pair = IFactoryMinimal(factoryAddr).getPair(address(token), wsrx);
+
+        emit Graduated(pair, srxLiquidity, tokenLiquidity, lpBurned);
+    }
+
+    // ── Internal helpers ──────────────────────────────────────────────
+    function _safeSendSRX(address to, uint256 amount) internal {
+        (bool ok,) = to.call{value: amount}("");
+        if (!ok) revert TransferFailed();
+    }
+
+    // Reject stray native SRX so accidental sends don't pollute the curve's
+    // accounting. Buyers must use buy().
+    receive() external payable {
+        if (msg.sender != router) revert TransferFailed();
+    }
+}