ERC-OTTER: Progressive Community Token Standard

// SPDX-License-Identifier: CC0-1.0
pragma solidity ^0.8.24;

/// @title IERC-OTTER: Progressive Community Token Standard
/// @notice Interface for community-owned tokens with immutable protection mechanics
/// @dev Extends ERC-20. All tax constants are immutable — no admin override possible.
interface IERC_OTTER {

    // ─── ENUMS ─────────────────────────────────────────────────────────────
    enum Tier { NEWCOMER, MEMBER, OG }
    enum ProposalStatus { PENDING, ACTIVE, PASSED, FAILED, EXECUTED, VETOED }

    // ─── EVENTS ────────────────────────────────────────────────────────────
    event TierUpgraded(address indexed holder, Tier oldTier, Tier newTier);
    event TaxDistributed(uint256 toTreasury, uint256 toRewards,
                         uint256 toLiquidity, uint256 burned);
    event MemeSubmitted(address indexed creator, bytes32 indexed contentHash,
                        uint256 indexed memeId);
    event MemeVoted(uint256 indexed memeId, address indexed voter,
                    bool upvote, uint256 weight);
    event EpochSettled(uint256 indexed epoch, uint256 distributed,
                       uint256 winnerCount);
    event RewardsClaimed(address indexed holder, uint256 amount);
    event ReferralRecorded(address indexed referrer, address indexed referee);
    event ProposalCreated(uint256 indexed id, address indexed proposer,
                          bytes32 descriptionHash);
    event ProposalPassed(uint256 indexed id, uint256 forVotes,
                         uint256 againstVotes);
    event GuardianAction(address indexed guardian, bytes4 selector, bytes32 reason);

    // ─── ERRORS ────────────────────────────────────────────────────────────
    error AlreadyVoted();
    error NothingToClaim();
    error InsufficientTier(Tier required, Tier actual);
    error GuardianOnly();
    error TimelockActive(uint256 unlocksAt);
    error ExceedsParameterBounds(uint256 value, uint256 min, uint256 max);

    // ─── HOLDER STATE (READ) ────────────────────────────────────────────────
    function holderTier(address account)      external view returns (Tier);
    function holdDuration(address account)    external view returns (uint256);
    function pendingRewards(address account)  external view returns (uint256);
    function rewardMultiplier(address account)external view returns (uint256 bps);
    function governanceWeight(address account)external view returns (uint256);
    function referralCount(address referrer)  external view returns (uint256);

    // ─── TAX CONSTANTS (IMMUTABLE — CANNOT BE CHANGED AFTER DEPLOY) ────────
    function TAX_RATE()        external view returns (uint16); // 500 = 5%
    function TREASURY_SHARE()  external view returns (uint16); // 4000 = 40%
    function REWARDS_SHARE()   external view returns (uint16); // 3000 = 30%
    function LIQUIDITY_SHARE() external view returns (uint16); // 2000 = 20%
    function BURN_SHARE()      external view returns (uint16); // 1000 = 10%

    // ─── COMMUNITY ACTIONS ─────────────────────────────────────────────────
    function submitMeme(bytes32 contentHash) external returns (uint256 memeId);
    function voteOnMeme(uint256 memeId, bool upvote) external;
    function claimRewards() external returns (uint256 claimed);
    function recordReferral(address referee, bytes32 proof) external;

    // ─── GOVERNANCE ────────────────────────────────────────────────────────
    function createProposal(bytes32 descriptionHash, bytes calldata payload)
        external returns (uint256 proposalId);
    function castVote(uint256 proposalId, bool support) external;
    function executeProposal(uint256 proposalId) external;
    function treasury() external view returns (address);

    // ─── PROTOCOL GUARDIAN ─────────────────────────────────────────────────
    // Guardian CAN: pause (max 24h), queue upgrades (72h timelock), veto proposals
    // Guardian CANNOT: change tax constants, access treasury, disable community mechanics
    function guardian() external view returns (address);
    function emergencyPause(uint256 duration) external; // MAX: 86400 seconds
    function queueUpgrade(address implementation) external; // 72h timelock
    function vetoProposal(uint256 proposalId, bytes32 reason) external;
    function setEpochDuration(uint256 days_) external; // bounds: 3–30 days
}

// Tier thresholds
uint256 constant MEMBER_THRESHOLD = 30 days;  // 2,592,000 seconds
uint256 constant OG_THRESHOLD     = 90 days;  // 7,776,000 seconds

// Reward multipliers in basis points
uint256 constant NEWCOMER_BPS = 10000; // 1.0x
uint256 constant MEMBER_BPS   = 15000; // 1.5x
uint256 constant OG_BPS       = 20000; // 2.0x

mapping(address => uint256) private _holdSince;

function holderTier(address account) public view returns (Tier) {
    uint256 held = holdDuration(account);
    if (held >= OG_THRESHOLD)     return Tier.OG;
    if (held >= MEMBER_THRESHOLD) return Tier.MEMBER;
    return Tier.NEWCOMER;
}

function holdDuration(address account) public view returns (uint256) {
    uint256 since = _holdSince[account];
    if (since == 0 || balanceOf(account) == 0) return 0;
    return block.timestamp - since;
}

/// @dev Resets hold timer on ANY outbound transfer — prevents gaming
function _afterTokenTransfer(address from, address to, uint256 amount)
    internal override
{
    if (from != address(0) && amount > 0) {
        // Seller loses all accumulated hold time
        _holdSince[from] = 0;
    }
    if (to != address(0) && _holdSince[to] == 0) {
        _holdSince[to] = block.timestamp;
    }
    _updateTierIfChanged(from);
    _updateTierIfChanged(to);
}

// ─── Epoch-Based Meme Reward Settlement ─────────────────────
uint256 public epochDuration;      // settable by Guardian: 3–30 days
uint256 public currentEpoch;
uint256 public epochStartTime;

struct Meme {
    address  creator;
    bytes32  contentHash;
    uint256  epoch;
    int256   netVotes;      // upvotes minus downvotes (weighted)
    uint256  rewardShare;   // set at settlement
    bool     settled;
}

/// @notice Settle current epoch: calculate shares, enable claiming.
/// @dev    Called by any address after epochDuration passes.
function settleEpoch() external {
    require(block.timestamp >= epochStartTime + epochDuration,
        "Epoch not over");

    uint256 poolBalance = rewardsPool.balance();
    uint256[] memory winners = _topMemes(currentEpoch, 10);

    uint256 totalWeight;
    for (uint i; i < winners.length; i++) {
        totalWeight += uint256(memes[winners[i]].netVotes);
    }

    for (uint i; i < winners.length; i++) {
        uint256 share = (poolBalance * uint256(
            memes[winners[i]].netVotes)) / totalWeight;
        memes[winners[i]].rewardShare = share;
        memes[winners[i]].settled = true;
    }

    emit EpochSettled(currentEpoch, poolBalance, winners.length);
    currentEpoch++;
    epochStartTime = block.timestamp;
}

// SPDX-License-Identifier: CC0-1.0
pragma solidity ^0.8.24;

/// @notice Protocol Guardian role — explicit power constraints on-chain
abstract contract OTTERGuardian {

    address public guardian;
    uint256 public upgradeTimelockExpiry;
    address public pendingImplementation;

    uint256 constant MAX_PAUSE_DURATION = 86400;    // 24 hours
    uint256 constant UPGRADE_TIMELOCK   = 259200;   // 72 hours
    uint256 constant MIN_EPOCH_DAYS     = 3;
    uint256 constant MAX_EPOCH_DAYS     = 30;

    modifier onlyGuardian() {
        require(msg.sender == guardian, "Guardian only");
        _;
    }

    /// @notice Pause all transfers for emergency. MAX 24 hours.
    function emergencyPause(uint256 duration) external onlyGuardian {
        require(duration <= MAX_PAUSE_DURATION,
            "Exceeds max pause duration");
        _pause(duration);
        emit GuardianAction(guardian, msg.sig, bytes32(duration));
    }

    /// @notice Queue an upgrade. 72-hour community observation window.
    function queueUpgrade(address implementation) external onlyGuardian {
        pendingImplementation = implementation;
        upgradeTimelockExpiry = block.timestamp + UPGRADE_TIMELOCK;
        emit GuardianAction(guardian, msg.sig, bytes32(uint256(
            uint160(implementation))));
    }

    /// @notice Execute queued upgrade only after timelock.
    function executeUpgrade() external onlyGuardian {
        require(block.timestamp >= upgradeTimelockExpiry,
            "Timelock not expired");
        _upgradeTo(pendingImplementation);
    }

    /// @notice Veto a governance proposal with on-chain reason.
    function vetoProposal(uint256 proposalId, bytes32 reason)
        external onlyGuardian
    {
        _vetoProposal(proposalId, reason);
        emit GuardianAction(guardian, msg.sig, reason);
    }

    /// @dev NOTE: TAX_RATE and distribution shares are declared as
    ///      'constant' — no setter exists. Guardian CANNOT modify them.

    function _pause(uint256) internal virtual;
    function _upgradeTo(address) internal virtual;
    function _vetoProposal(uint256, bytes32) internal virtual;
}