enum ProposalState {
    Pending, // 等待状态，开始投票之前
    Active, // 开始投票了
    Canceled, // 提案被取消了
    Defeated, // 提案失败了
    Succeeded, // 提案成功了
    Queued, // 提案进入排队
    Expired, // 提案到期了
    Executed // 提案被执行
}

event ProposalCreated( // 当一个proposal被创建的时候抛出
	uint256 proposalId,
	address proposer,
	address[] targets,
	uint256[] values,
	string[] signatures,
	bytes[] calldatas,
	uint256 startBlock,
	uint256 endBlock,
	string description
);

event ProposalCanceled( // 当proposal被取消的时候抛出
	uint256 proposalId
);

event ProposalExecuted( // 当proposal被执行的时候抛出
	uint256 proposalId
);

event VoteCast( // 投票的时候抛出
	address indexed voter, 
	uint256 proposalId, 
	uint8 support, 
	uint256 weight, 
	string reason
);
 
event VoteCastWithParams( // 带有参数的投票的时候抛出
    address indexed voter,
    uint256 proposalId,
    uint8 support,
    uint256 weight,
    string reason,
    bytes params
);

// 返回名字
function name() public view virtual returns (string memory);

// 返回版本
function version() public view virtual returns (string memory);

// 传入 Proposal 的所有信息，然后返回一个他们整合后的keccak256加密后的hash值
// 这个值就是这个 proposal 的 id
function hashProposal(
    address[] memory targets,
    uint256[] memory values,
    bytes[] memory calldatas,
    bytes32 descriptionHash
) public pure virtual override returns (uint256);

// snapshot其实就是返回vote开始的区块的高度
function proposalSnapshot(uint256 proposalId) public view virtual returns (uint256);

// deadline其实就是返回vote结束的区块的高度
function proposalDeadline(uint256 proposalId) public view virtual returns (uint256);

// 发起一个Proposal
function propose(
        address[] memory targets,
        uint256[] memory values,
        bytes[] memory calldatas,
        string memory description
    ) public virtual returns (uint256 proposalId);

// 执行一个Proposal
// 涉及到三个内部函数 _beforeExecute(), _execute(), _afterExecute()
function execute(
        address[] memory targets,
        uint256[] memory values,
        bytes[] memory calldatas,
        bytes32 descriptionHash
    ) public payable virtual returns (uint256 proposalId);

function state(uint256 proposalId) public view virtual returns (ProposalState);

function votingDelay() public view virtual returns (uint256);
function votingPeriod() public view virtual returns (uint256);
function quorum(uint256 blockNumber) public view virtual returns (uint256);

// 没有传入 params，使用默认的_defaultParams()
function getVotes(address account, uint256 blockNumber) public view virtual returns (uint256);

function getVotesWithParams(
        address account,
        uint256 blockNumber,
        bytes memory params
    ) public view virtual returns (uint256);

function COUNTING_MODE() public pure virtual returns (string memory);

function hasVoted(uint256 proposalId, address account) public view virtual returns (bool);

function castVote(uint256 proposalId, uint8 support) public virtual returns (uint256 balance);

function castVoteWithReason(
        uint256 proposalId,
        uint8 support,
        string calldata reason
    ) public virtual returns (uint256 balance);

function castVoteWithReasonAndParams(
        uint256 proposalId,
        uint8 support,
        string calldata reason,
        bytes memory params
    ) public virtual returns (uint256 balance);


function castVoteBySig(
        uint256 proposalId,
        uint8 support,
        uint8 v,
        bytes32 r,
        bytes32 s
    ) public virtual returns (uint256 balance);


function castVoteWithReasonAndParamsBySig(
        uint256 proposalId,
        uint8 support,
        string calldata reason,
        bytes memory params,
        uint8 v,
        bytes32 r,state
        bytes32 s
    ) public virtual returns (uint256 balance);

struct ProposalCore {
    Timers.BlockNumber voteStart; // 记录这个Proposal的投票开始时间(区块号)
    Timers.BlockNumber voteEnd; // 记录这个Proposal的投票结束时间(区块号)
    bool executed; // 这个Proposal是否被执行
    bool canceled; // 这个Proposal是否被取消
}

function propose(
        address[] memory targets, // 提案操作的一系列地址
        uint256[] memory values, // 提案操作的一系列value，也就是转多少钱
        bytes[] memory calldatas, // 提案操作的一系列地址中的具体函数
        string memory description // 对于提案的描述
    ) public virtual override returns (uint256);

bytes32 public constant BALLOT_TYPEHASH = keccak256("Ballot(uint256 proposalId,uint8 support)");

bytes32 public constant EXTENDED_BALLOT_TYPEHASH =
    keccak256("ExtendedBallot(uint256 proposalId,uint8 support,string reason,bytes params)");

// 治理合约的名字
string private _name;

// 用来存 Proposal 的结构 (proposalId --> proposalCore)
// 我们知道 proposalCore 里实际是没有 Proposal 的执行信息的
mapping(uint256 => ProposalCore) private _proposals;

// 这个队列是一个追踪队列，我们知道操作的本质是一系列的Transaction
// 而Transaction则是 (target, value, calldata) 组成的 target.call {value: value} (calldata)
// 当 target = this，即治理合约本身的时候，我们会将 calldata 记录下来
// 而当合约中被 onlyGovernance 保护的函数被外部合约调用的时候，我们需要确保这个操作是被记录在这个队列当中的
// 这个变量是和 Modifier onlyGovernance() 协作的，在后面将 onlyGovernance 会详细讲
DoubleEndedQueue.Bytes32Deque private _governanceCall;

modifier onlyGovernance() {
    require(_msgSender() == _executor(), "Governor:  onlyGovernance"); // 调用者必须是executor
    if (_executor() != address(this)) {
        bytes32 msgDataHash = keccak256(_msgData());
        // loop until popping the expected operation - throw if deque is empty (operation not authorized)
        while (_governanceCall.popFront() != msgDataHash) {} // 调用函数必须在白名单里
    }
    _;
}

function relay(
    address target,
    uint256 value,
    bytes calldata data
) external virtual onlyGovernance {
    Address.functionCallWithValue(target, data, value); // 转钱函数
}

function execute(
        address[] memory targets,
        uint256[] memory values,
        bytes[] memory calldatas,
        bytes32 descriptionHash
    ) public payable virtual override returns (uint256) {
        uint256 proposalId = hashProposal(targets, values, calldatas, descriptionHash);

        ProposalState status = state(proposalId);
        require(
            status == ProposalState.Succeeded || status == ProposalState.Queued,
            "Governor: proposal not successful"
        );
        _proposals[proposalId].executed = true;

        emit ProposalExecuted(proposalId);

        _beforeExecute(proposalId, targets, values, calldatas, descriptionHash); // 注册到_governanceCall中
        _execute(proposalId, targets, values, calldatas, descriptionHash); // 执行 operations
        _afterExecute(proposalId, targets, values, calldatas, descriptionHash); // 清空_governanceCall，防止权限泄露

        return proposalId;
    }

function propose(
    address[] memory targets,
    uint256[] memory values,
    bytes[] memory calldatas,
    string memory description
) public virtual override returns (uint256) {
    // 有没有资格成为proposer
    require(
        getVotes(_msgSender(), block.number - 1) >= proposalThreshold(),
        "Governor: proposer votes below proposal threshold"
    );
    
    // 计算proposal的id
    uint256 proposalId = hashProposal(targets, values, calldatas, keccak256(bytes(description)));

    // targets，values，calldatas的需要相等
    require(targets.length == values.length, "Governor: invalid proposal length");
    require(targets.length == calldatas.length, "Governor: invalid proposal length");
    require(targets.length > 0, "Governor: empty proposal");

    // 去_proposals里创建一个ProposalCore，里面只记录proposal流程相关的信息，而不会去记录proposal执行相关的具体信息。
    ProposalCore storage proposal = _proposals[proposalId];
    // 判断这个ProposalCore的voteStart有没有设置，其实就是判断这个Proposal有没有被提出过
    require(proposal.voteStart.isUnset(), "Governor: proposal already exists");

    // 获取两个信息，开始投票的时间 和 结束投票的时间。
    // 相关的 votingDelay() 和 votingPeriod() 函数需要用户自己去设计
    uint64 snapshot = block.number.toUint64() + votingDelay().toUint64();
    uint64 deadline = snapshot + votingPeriod().toUint64();

    // 把上面获取到的信息，存到ProposalCore中对应的voteStart和voteEnd
    proposal.voteStart.setDeadline(snapshot);
    proposal.voteEnd.setDeadline(deadline);

    // 抛出ProposalCreated事件
    emit ProposalCreated(
        proposalId,
        _msgSender(),
        targets,
        values,
        new string[](targets.length),
        calldatas,
        snapshot,
        deadline,
        description
    );

    return proposalId;
}

function execute(
    address[] memory targets,
    uint256[] memory values,
    bytes[] memory calldatas,
    bytes32 descriptionHash
) public payable virtual override returns (uint256) {
    // 根据proposal的执行信息，计算proposl的id
    uint256 proposalId = hashProposal(targets, values, calldatas, descriptionHash);

    // 获取propsal当前的state
    ProposalState status = state(proposalId);
    
    // state需要处在 Succeeded 或者 Queued
    require(
        status == ProposalState.Succeeded || status == ProposalState.Queued,
        "Governor: proposal not successful"
    );
    _proposals[proposalId].executed = true;

    // 抛出ProposalExecuted事件
    emit ProposalExecuted(proposalId);

    // _beforeExecute前面说过了，就是添加txs白名单
    _beforeExecute(proposalId, targets, values, calldatas, descriptionHash);
    // 执行proposal中提出的operation中的txs
    _execute(proposalId, targets, values, calldatas, descriptionHash);
    // 清空白名单
    _afterExecute(proposalId, targets, values, calldatas, descriptionHash);

    return proposalId;
}

function _execute(
    uint256, /* proposalId */
    address[] memory targets,
    uint256[] memory values,
    bytes[] memory calldatas,
    bytes32 /*descriptionHash*/
) internal virtual {
    string memory errorMessage = "Governor: call reverted without message";
    for (uint256 i = 0; i < targets.length; ++i) { // 遍历operation里的txs
        (bool success, bytes memory returndata) = targets[i].call{value: values[i]}(calldatas[i]); // 通过call发起tx
        Address.verifyCallResult(success, returndata, errorMessage); // 对call的返回结果进行处理，其实如果success为true，便没啥特别的处理。但是如果是false的话，就会特别处理以决定抛出什么异常信息
    }
}

function name() public view virtual override returns (string memory) {
    return _name; // 返回_name
}

function version() public view virtual override returns (string memory) {
    return "1"; // 直接返回写死的值

function hashProposal(
    address[] memory targets,
    uint256[] memory values,
    bytes[] memory calldatas,
    bytes32 descriptionHash
) public pure virtual override returns (uint256) {
    return uint256(keccak256(abi.encode(targets, values, calldatas, descriptionHash))); // 使用keccak256进行hash
}

function proposalSnapshot(uint256 proposalId) public view virtual override returns (uint256) {
    return _proposals[proposalId].voteStart.getDeadline(); // 获取voteStart
}

function proposalDeadline(uint256 proposalId) public view virtual override returns (uint256) {
    return _proposals[proposalId].voteEnd.getDeadline(); // 获取voteEnd
}