事件与接口（草案）

草案

以下接口草图用于讨论，不是最终 ABI。函数签名、参数类型和事件字段都可能变化。

Factory

// 草案
struct LaunchParams {
    string  name;
    string  symbol;
    string  metadataURI;      // 图片、链接
    address quoteAsset;       // 必须在本链白名单内
    uint16  feeTierBps;       // 100..500，步长 100
    uint16  creatorShareBps;  // 0..4000（占手续费）
    address creatorRecipient;
    uint256 targetFdv;        // 市值，4.2–42 ETH
    uint16  incentiveBps;     // 激励池 x，由 Factory 校验上限
    uint8   underfillRule;    // 0 = 退款, 1 = 保价缩量
    uint32  saleDuration;     // 例如 48h
    bytes32 whitelistRoot;    // 叶子: (address, cap)
    uint8   treasuryMode;     // 0 = 回购本币, 1 = 按 TWAB 回馈持有人
}

interface IPortusFactory {
    function createToken(LaunchParams calldata p)
        external returns (address token, address sale, address pool, address treasury);

    function isQuoteAssetAllowed(address asset) external view returns (bool);

    event TokenLaunched(
        address indexed token, address indexed creator, address indexed quoteAsset,
        address sale, address pool, address treasury, LaunchParams params
    );
}

Sale

// 草案
interface IPortusSale {
    function subscribe(uint256 amount, uint256 cap, bytes32[] calldata proof) external;
    function finalize() external;            // 认购期结束后任何人可调用
    function claimTokens() external;
    function claimRefund() external;

    function raiseTarget() external view returns (uint256);   // R
    function totalCommitted() external view returns (uint256);// C
    function price() external view returns (uint256);         // p

    event Subscribed(address indexed user, uint256 amount);
    event Finalized(uint8 outcome, uint256 raised, uint256 fillRatioBps, uint256 burned);
    event Claimed(address indexed user, uint256 tokens, uint256 refund);
}

Pool

// 草案
interface IPortusPool {
    function swap(bool buy, uint256 amountIn, uint256 minAmountOut, address to)
        external returns (uint256 amountOut, uint256 feeInQuote);
    function getAmountOut(bool buy, uint256 amountIn)
        external view returns (uint256 amountOut, uint256 feeInQuote);
    function getReserves() external view returns (uint256 quoteReserve, uint256 tokenReserve);
    function priceCumulative() external view returns (uint256); // 供 TWAP 使用

    event Swap(address indexed sender, bool buy, uint256 amountIn, uint256 amountOut,
               uint256 feeInQuote, address indexed to);
}

FeeSplitter / Treasury / Distributor

// 草案
interface IPortusFeeSplitter {
    function shares(address token) external view
        returns (uint16 platformBps, uint16 flywheelBps, uint16 creatorBps, uint16 treasuryBps);
    function claim(address token) external; // 收款方自行领取
    event FeeSplit(address indexed token, uint256 platform, uint256 flywheel,
                   uint256 creator, uint256 treasury);
}

interface IPortusTreasury {
    function executeBuyback(uint256 maxQuoteIn, uint256 minTokensOut) external; // 任何人
    event Buyback(uint256 quoteSpent, uint256 tokensBought);
}

interface IPortusDistributor {
    function claim(uint256 epoch, uint256 amount, bytes32[] calldata proof) external;
    event RootPublished(uint256 indexed epoch, bytes32 root, uint256 total, string dataURI);
    event Claimed(uint256 indexed epoch, address indexed user, uint256 amount);
}