ERC-5727: 半同质化灵魂绑定代币

/**
 * @title ERC5727 Soulbound Token Interface
 * @dev The core interface of the ERC5727 standard.
 * @title ERC5727 灵魂绑定代币接口
 * @dev ERC5727 标准的核心接口。
 */
interface IERC5727 is IERC3525, IERC5192, IERC5484, IERC4906 {
    /**
     * @dev MUST emit when a token is revoked.
     * @param from The address of the owner
     * @param tokenId The token id
     * @dev 必须在代币被撤销时发出。
     * @param from 所有者的地址
     * @param tokenId 代币 ID
     */
    event Revoked(address indexed from, uint256 indexed tokenId);

    /**
     * @dev MUST emit when a token is verified.
     * @param by The address that initiated the verification
     * @param tokenId The token id
     * @param result The result of the verification
     * @dev 必须在代币被验证时发出。
     * @param by 发起验证的地址
     * @param tokenId 代币 ID
     * @param result 验证结果
     */
    event Verified(address indexed by, uint256 indexed tokenId, bool result);

    /**
     * @notice Get the verifier of a token.
     * @dev MUST revert if the `tokenId` does not exist
     * @param tokenId the token for which to query the verifier
     * @return The address of the verifier of `tokenId`
     * @notice 获取代币的验证者。
     * @dev 如果 `tokenId` 不存在，则必须恢复
     * @param tokenId 要查询验证者的代币
     * @return `tokenId` 的验证者的地址
     */
    function verifierOf(uint256 tokenId) external view returns (address);

    /**
     * @notice Get the issuer of a token.
     * @dev MUST revert if the `tokenId` does not exist
     * @param tokenId the token for which to query the issuer
     * @return The address of the issuer of `tokenId`
     * @notice 获取代币的发行者。
     * @dev 如果 `tokenId` 不存在，则必须恢复
     * @param tokenId 要查询发行者的代币
     * @return `tokenId` 的发行者的地址
     */
    function issuerOf(uint256 tokenId) external view returns (address);

    /**
     * @notice Issue a token in a specified slot to an address.
     * @dev MUST revert if the `to` address is the zero address.
     *      MUST revert if the `verifier` address is the zero address.
     * @param to The address to issue the token to
     * @param tokenId The token id
     * @param slot The slot to issue the token in
     * @param burnAuth The burn authorization of the token
     * @param verifier The address of the verifier
     * @param data Additional data used to issue the token
     * @notice 向地址中的指定插槽发行代币。
     * @dev 如果 `to` 地址为零地址，则必须恢复。
     *      如果 `verifier` 地址为零地址，则必须恢复。
     * @param to 要向其发行代币的地址
     * @param tokenId 代币 ID
     * @param slot 要在其中发行代币的插槽
     * @param burnAuth 代币的销毁授权
     * @param verifier 验证者的地址
     * @param data 用于发行代币的附加数据
     */
    function issue(
        address to,
        uint256 tokenId,
        uint256 slot,
        BurnAuth burnAuth,
        address verifier,
        bytes calldata data
    ) external payable;

    /**
     * @notice Issue credit to a token.
     * @dev MUST revert if the `tokenId` does not exist.
     * @param tokenId The token id
     * @param amount The amount of the credit
     * @param data The additional data used to issue the credit
     * @notice 向代币发行信用。
     * @dev 如果 `tokenId` 不存在，则必须恢复。
     * @param tokenId 代币 ID
     * @param amount 信用额度
     * @param data 用于发行信用的附加数据
     */
    function issue(
        uint256 tokenId,
        uint256 amount,
        bytes calldata data
    ) external payable;

    /**
     * @notice Revoke a token from an address.
     * @dev MUST revert if the `tokenId` does not exist.
     * @param tokenId The token id
     * @param data The additional data used to revoke the token
     * @notice 从地址撤销代币。
     * @dev 如果 `tokenId` 不存在，则必须恢复。
     * @param tokenId 代币 ID
     * @param data 用于撤销代币的附加数据
     */
    function revoke(uint256 tokenId, bytes calldata data) external payable;

    /**
     * @notice Revoke credit from a token.
     * @dev MUST revert if the `tokenId` does not exist.
     * @param tokenId The token id
     * @param amount The amount of the credit
     * @param data The additional data used to revoke the credit
     * @notice 从代币撤销信用。
     * @dev 如果 `tokenId` 不存在，则必须恢复。
     * @param tokenId 代币 ID
     * @param amount 信用额度
     * @param data 用于撤销信用的附加数据
     */
    function revoke(
        uint256 tokenId,
        uint256 amount,
        bytes calldata data
    ) external payable;

    /**
     * @notice Verify if a token is valid.
     * @dev MUST revert if the `tokenId` does not exist.
     * @param tokenId The token id
     * @param data The additional data used to verify the token
     * @return A boolean indicating whether the token is successfully verified
     * @notice 验证代币是否有效。
     * @dev 如果 `tokenId` 不存在，则必须恢复。
     * @param tokenId 代币 ID
     * @param data 用于验证代币的附加数据
     * @return 一个布尔值，指示代币是否已成功验证
     */
    function verify(
        uint256 tokenId,
        bytes calldata data
    ) external returns (bool);
}

/**
 * @title ERC5727 Soulbound Token Enumerable Interface
 * @dev This extension allows querying the tokens of a owner.
 * @title ERC5727 灵魂绑定代币可枚举接口
 * @dev 此扩展允许查询所有者的代币。
 */
interface IERC5727Enumerable is IERC3525SlotEnumerable, IERC5727 {
    /**
     * @notice Get the number of slots of a owner.
     * @param owner The owner whose number of slots is queried for
     * @return The number of slots of the `owner`
     * @notice 获取所有者的插槽数量。
     * @param owner 要查询其插槽数量的所有者
     * @return `owner` 的插槽数量
     */
    function slotCountOfOwner(address owner) external view returns (uint256);

    /**
     * @notice Get the slot with `index` of the `owner`.
     * @dev MUST revert if the `index` exceed the number of slots of the `owner`.
     * @param owner The owner whose slot is queried for.
     * @param index The index of the slot queried for
     * @return The slot is queried for
     * @notice 获取带有 `owner` 的 `index` 的插槽。
     * @dev 如果 `index` 超过 `owner` 的插槽数量，则必须恢复。
     * @param owner 要查询其插槽的所有者。
     * @param index 要查询的插槽的索引
     * @return 查询的插槽
     */
    function slotOfOwnerByIndex(
        address owner,
        uint256 index
    ) external view returns (uint256);

    /**
     * @notice Get the balance of a owner in a slot.
     * @dev MUST revert if the slot does not exist.
     * @param owner The owner whose balance is queried for
     * @param slot The slot whose balance is queried for
     * @return The balance of the `owner` in the `slot`
     * @notice 获取所有者在插槽中的余额。
     * @dev 如果插槽不存在，则必须恢复。
     * @param owner 要查询其余额的所有者
     * @param slot 要查询其余额的插槽
     * @return `owner` 在 `slot` 中的余额
     */
    function ownerBalanceInSlot(
        address owner,
        uint256 slot
    ) external view returns (uint256);
}

/**
 * @title ERC5727 Soulbound Token Metadata Interface
 * @dev This extension allows querying the metadata of soulbound tokens.
 * @title ERC5727 灵魂绑定代币元数据接口
 * @dev 此扩展允许查询灵魂绑定代币的元数据。
 */
interface IERC5727Metadata is IERC3525Metadata, IERC5727 {

}

/**
 * @title ERC5727 Soulbound Token Governance Interface
 * @dev This extension allows issuing of tokens by community voting.
 * @title ERC5727 灵魂绑定代币治理接口
 * @dev 此扩展允许通过社区投票发行代币。
 */
interface IERC5727Governance is IERC5727 {
    enum ApprovalStatus {
        Pending,
        Approved,
        Rejected,
        Removed
    }

    /**
     * @notice Emitted when a token issuance approval is changed.
     * @param approvalId The id of the approval
     * @param creator The creator of the approval, zero address if the approval is removed
     * @param status The status of the approval
     * @notice 当代币发行批准发生更改时发出。
     * @param approvalId 批准的 ID
     * @param creator 批准的创建者，如果批准被移除，则为零地址
     * @param status 批准的状态
     */
    event ApprovalUpdate(
        uint256 indexed approvalId,
        address indexed creator,
        ApprovalStatus status
    );

    /**
     * @notice Emitted when a voter approves an approval.
     * @param voter The voter who approves the approval
     * @param approvalId The id of the approval
     * @notice 当选民批准批准时发出。
     * @param voter 批准批准的选民
     * @param approvalId 批准的 ID
     */
    event Approve(
        address indexed voter,
        uint256 indexed approvalId,
        bool approve
    );

    /**
     * @notice Create an approval of issuing a token.
     * @dev MUST revert if the caller is not a voter.
     *      MUST revert if the `to` address is the zero address.
     * @param to The owner which the token to mint to
     * @param tokenId The id of the token to mint
     * @param amount The amount of the token to mint
     * @param slot The slot of the token to mint
     * @param burnAuth The burn authorization of the token to mint
     * @param data The additional data used to mint the token
     * @notice 创建发行代币的批准。
     * @dev 如果调用者不是选民，则必须恢复。
     *      如果 `to` 地址为零地址，则必须恢复。
     * @param to 要向其铸造代币的所有者
     * @param tokenId 要铸造的代币的 ID
     * @param amount 要铸造的代币的数量
     * @param slot 要铸造的代币的插槽
     * @param burnAuth 要铸造的代币的销毁授权
     * @param data 用于铸造代币的附加数据
     */
    function requestApproval(
        address to,
        uint256 tokenId,
        uint256 amount,
        uint256 slot,
        BurnAuth burnAuth,
        address verifier,
        bytes calldata data
    ) external;

    /**
     * @notice Remove `approvalId` approval request.
     * @dev MUST revert if the caller is not the creator of the approval request.
     *      MUST revert if the approval request is already approved or rejected or non-existent.
     * @param approvalId The approval to remove
     * @notice 移除 `approvalId` 批准请求。
     * @dev 如果调用者不是批准请求的创建者，则必须恢复。
     *      如果批准请求已被批准或拒绝或不存在，则必须恢复。
     * @param approvalId 要移除的批准
     */
    function removeApprovalRequest(uint256 approvalId) external;

    /**
     * @notice Approve `approvalId` approval request.
     * @dev MUST revert if the caller is not a voter.
     *     MUST revert if the approval request is already approved or rejected or non-existent.
     * @param approvalId The approval to approve
     * @param approve True if the approval is approved, false if the approval is rejected
     * @param data The additional data used to approve the approval (e.g. the signature, voting power)
     * @notice 批准 `approvalId` 批准请求。
     * @dev 如果调用者不是选民，则必须恢复。
     *     如果批准请求已被批准或拒绝或不存在，则必须恢复。
     * @param approvalId 要批准的批准
     * @param approve 如果批准被批准，则为 True，如果批准被拒绝，则为 False
     * @param data 用于批准批准的附加数据（例如签名、投票权）
     */
    function voteApproval(
        uint256 approvalId,
        bool approve,
        bytes calldata data
    ) external;

    /**
     * @notice Get the URI of the approval.
     * @dev MUST revert if the `approvalId` does not exist.
     * @param approvalId The approval whose URI is queried for
     * @return The URI of the approval
     * @notice 获取批准的 URI。
     * @dev 如果 `approvalId` 不存在，则必须恢复。
     * @param approvalId 要查询其 URI 的批准
     * @return 批准的 URI
     */
    function approvalURI(
        uint256 approvalId
    ) external view returns (string memory);
}

/**
 * @title ERC5727 Soulbound Token Delegate Interface
 * @dev This extension allows delegation of issuing and revocation of tokens to an operator.
 * @title ERC5727 灵魂绑定代币委托接口
 * @dev 此扩展允许将代币的发行和撤销委托给操作员。
 */
interface IERC5727Delegate is IERC5727 {
    /**
     * @notice Emitted when a token issuance is delegated to an operator.
     * @param operator The owner to which the issuing right is delegated
     * @param slot The slot to issue the token in
     * @notice 当代币发行被委托给操作员时发出。
     * @param operator 向其委托发行权的所有者
     * @param slot 要在其中发行代币的插槽
     */
    event Delegate(address indexed operator, uint256 indexed slot);

    /**
     * @notice Emitted when a token issuance is revoked from an operator.
     * @param operator The owner to which the issuing right is delegated
     * @param slot The slot to issue the token in
     * @notice 当从操作员处撤销代币发行时发出。
     * @param operator 向其委托发行权的所有者
     * @param slot 要在其中发行代币的插槽
     */
    event UnDelegate(address indexed operator, uint256 indexed slot);

    /**
     * @notice Delegate rights to `operator` for a slot.
     * @dev MUST revert if the caller does not have the right to delegate.
     *      MUST revert if the `operator` address is the zero address.
     *      MUST revert if the `slot` is not a valid slot.
     * @param operator The owner to which the issuing right is delegated
     * @param slot The slot to issue the token in
     * @notice 将插槽的权利委托给 `operator`。
     * @dev 如果调用者没有委托的权利，则必须恢复。
     *      如果 `operator` 地址为零地址，则必须恢复。
     *      如果 `slot` 不是有效插槽，则必须恢复。
     * @param operator 向其委托发行权的所有者
     * @param slot 要在其中发行代币的插槽
     */
    function delegate(address operator, uint256 slot) external;

    /**
     * @notice Revoke rights from `operator` for a slot.
     * @dev MUST revert if the caller does not have the right to delegate.
     *      MUST revert if the `operator` address is the zero address.
     *      MUST revert if the `slot` is not a valid slot.
     * @param operator The owner to which the issuing right is delegated
     * @param slot The slot to issue the token in
     * @notice 从 `operator` 处撤销插槽的权利。
     * @dev 如果调用者没有委托的权利，则必须恢复。
     *      如果 `operator` 地址为零地址，则必须恢复。
     *      如果 `slot` 不是有效插槽，则必须恢复。
     * @param operator 向其委托发行权的所有者
     * @param slot 要在其中发行代币的插槽
     */

    function undelegate(address operator, uint256 slot) external;

    /**
     * @notice Check if an operator has the permission to issue or revoke tokens in a slot.
     * @param operator The operator to check
     * @param slot The slot to check
     * @notice 检查操作员是否具有在插槽中发行或撤销代币的权限。
     * @param operator 要检查的操作员
     * @param slot 要检查的插槽
     */
    function isOperatorFor(
        address operator,
        uint256 slot
    ) external view returns (bool);
}

/**
 * @title ERC5727 Soulbound Token Recovery Interface
 * @dev This extension allows recovering soulbound tokens from an address provided its signature.
 * @title ERC5727 灵魂绑定代币恢复接口
 * @dev 此扩展允许从提供其签名的地址中恢复灵魂绑定代币。
 */
interface IERC5727Recovery is IERC5727 {
    /**
     * @notice Emitted when the tokens of `owner` are recovered.
     * @param from The owner whose tokens are recovered
     * @param to The new owner of the tokens
     * @notice 当 `owner` 的代币被恢复时发出。
     * @param from 其代币被恢复的所有者
     * @param to 代币的新所有者
     */
    event Recovered(address indexed from, address indexed to);

    /**
     * @notice Recover the tokens of `owner` with `signature`.
     * @dev MUST revert if the signature is invalid.
     * @param owner The owner whose tokens are recovered
     * @param signature The signature signed by the `owner`
     * @notice 使用 `signature` 恢复 `owner` 的代币。
     * @dev 如果签名无效，则必须恢复。
     * @param owner 其代币被恢复的所有者
     * @param signature 由 `owner` 签名的签名
     */
    function recover(address owner, bytes memory signature) external;
}

/**
 * @title ERC5727 Soulbound Token Expirable Interface
 * @dev This extension allows soulbound tokens to be expirable and renewable.
 * @title ERC5727 灵魂绑定代币可过期接口
 * @dev 此扩展允许灵魂绑定代币可过期和可续订。
 */
interface IERC5727Expirable is IERC5727, IERC5643 {
    /**
     * @notice Set the expiry date of a token.
     * @dev MUST revert if the `tokenId` token does not exist.
     *      MUST revert if the `date` is in the past.
     * @param tokenId The token whose expiry date is set
     * @param expiration The expire date to set
     * @param isRenewable Whether the token is renewable
     * @notice 设置代币的到期日期。
     * @dev 如果 `tokenId` 代币不存在，则必须恢复。
     *      如果 `date` 在过去，则必须恢复。
     * @param tokenId 要设置其到期日期的代币
     * @param expiration 要设置的到期日期
     * @param isRenewable 代币是否可续订
     */
    function setExpiration(
        uint256 tokenId,
        uint64 expiration,
        bool isRenewable
    ) external;
}