hss-system-contract

Hedera 调度服务（HSS）系统合约

位于 0x16b 的 Hedera 调度服务系统合约提供了可在 Solidity 中创建和管理定时交易的函数。它支持：

• HIP-755：在合约中授权和签署调度
• HIP-756：调度原生 HTS 代币创建（createFungibleToken、createNonFungibleToken 等）
• HIP-1215：通用定时合约调用——调度对任意合约（或自身）的调用，用于 DeFi 自动化、归属计划、DAO 操作

快速参考

合约地址： 0x16b

导入：

import {HederaScheduleService} from "@hashgraph/smart-contracts/contracts/system-contracts/hedera-schedule-service/HederaScheduleService.sol";
import {IHRC1215ScheduleFacade} from "@hashgraph/smart-contracts/contracts/system-contracts/hedera-schedule-service/IHRC1215ScheduleFacade.sol";

HederaScheduleService 是一个抽象合约（类似于用于 HTS 的 HederaTokenService）。继承它即可获得处理对 0x16b 低级调用的 internal 辅助函数。HederaResponseCodes 可传递使用。

响应码： SUCCESS = 22（HederaResponseCodes.SUCCESS）。完整函数列表请参阅 references/api.md，响应码请参阅 Hedera 响应码。

关键：继承模式

IHederaScheduleService 是一个空接口。 函数定义在 IHRC755、IHRC756、IHRC1215 中，并在 HederaScheduleService 中封装为 internal 辅助函数。你的合约必须继承 HederaScheduleService：

contract MyScheduler is HederaScheduleService {
    error ScheduleFailed();

    function doSchedule() external {
        (int64 rc, address scheduleAddr) = scheduleCall(target, expiry, gasLimit, 0, data);
        if (rc != HederaResponseCodes.SUCCESS) revert ScheduleFailed();
    }
}

关键：不回滚行为（HIP-1215）

scheduleCall、scheduleCallWithPayer 和 executeCallOnPayerSignature 函数不会回滚。失败时会返回 (responseCode, address(0))。请务必检查：

error ScheduleFailed();

(int64 rc, address scheduleAddr) = scheduleCall(target, expiry, gasLimit, 0, data);
if (rc != HederaResponseCodes.SUCCESS || scheduleAddr == address(0)) {
    revert ScheduleFailed();
}

容量与限流（HIP-1215）

定时调用按秒限流。调度前请使用 hasScheduleCapacity(expirySecond, gasLimit)，以避免出现 SCHEDULE_EXPIRY_IS_BUSY：

bool capacity = hasScheduleCapacity(expirySecond, gasLimit);
if (!capacity) {
    // Retry with a later expiry or different gas limit
    // See HIP-1215 findAvailableSecond() pattern for exponential backoff + jitter
}

常见概念

• 定时交易：封装 Hedera 交易（原生 HTS 调用或 EVM 合约调用），在满足签名阈值后延迟执行。
• 付款方：负责支付费用的账户。使用 scheduleCall 时，调用合约就是付款方。使用 scheduleCallWithPayer / executeCallOnPayerSignature 时，可以指定单独的付款方。
• authorizeSchedule：使用调用合约的密钥（ContractKey 格式为 0.0.<ContractId>）签署调度。
• signSchedule：添加来自 EOA 或其他密钥的 protobuf 编码签名。
• 过期时间：如果调度在 expirySecond 之前未收集到所有必需签名，就会自动从网络中移除。

使用模式

调度原生代币创建（HIP-756）

注意： 调度执行时，付款方必须有足够的 HBAR（用于支付代币创建费用）。

import {HederaScheduleService} from "@hashgraph/smart-contracts/contracts/system-contracts/hedera-schedule-service/HederaScheduleService.sol";
import {IHederaTokenService} from "@hashgraph/smart-contracts/contracts/system-contracts/hedera-token-service/IHederaTokenService.sol";

contract ScheduledTokenCreator is HederaScheduleService {
    error FailToSchedule();

    function scheduleTokenCreate(
        IHederaTokenService.HederaToken memory token,
        int64 initialSupply,
        int32 decimals,
        address payer
    ) external returns (address scheduleAddr) {
        bytes memory callData = abi.encodeCall(
            IHederaTokenService.createFungibleToken,
            (token, initialSupply, decimals)
        );
        int64 rc;
        (rc, scheduleAddr) = scheduleNative(
            address(0x167), callData, payer
        );
        if (rc != HederaResponseCodes.SUCCESS) revert FailToSchedule();
    }
}

调度任意合约调用（HIP-1215）

import {HederaScheduleService} from "@hashgraph/smart-contracts/contracts/system-contracts/hedera-schedule-service/HederaScheduleService.sol";

contract Scheduler is HederaScheduleService {
    error FailToSchedule();
    event ScheduleCreated(address);

    function scheduleFutureCall(
        address target,
        uint256 expirySecond,
        uint256 gasLimit,
        bytes memory callData
    ) external returns (address scheduleAddr) {
        if (!hasScheduleCapacity(expirySecond, gasLimit)) revert FailToSchedule();

        int64 rc;
        (rc, scheduleAddr) = scheduleCall(
            target,
            expirySecond > 0 ? expirySecond : block.timestamp + 5,
            gasLimit,
            0,
            callData
        );
        if (rc != HederaResponseCodes.SUCCESS) {
            revert FailToSchedule();
        }
        emit ScheduleCreated(scheduleAddr);
    }
}

合约签署调度（HIP-755）

import {HederaScheduleService} from "@hashgraph/smart-contracts/contracts/system-contracts/hedera-schedule-service/HederaScheduleService.sol";

contract ScheduleSigner is HederaScheduleService {
    error FailToAuthorize();
    error FailToSign();

    function signAsContract(address scheduleAddr) external {
        int64 rc = authorizeSchedule(scheduleAddr);
        if (rc != HederaResponseCodes.SUCCESS) revert FailToAuthorize();
    }

    function signWithSignatureMap(address scheduleAddr, bytes memory sigMap) external {
        int64 rc = signSchedule(scheduleAddr, sigMap);
        if (rc != HederaResponseCodes.SUCCESS) revert FailToSign();
    }
}

删除调度

import {HederaScheduleService} from "@hashgraph/smart-contracts/contracts/system-contracts/hedera-schedule-service/HederaScheduleService.sol";
import {IHRC1215ScheduleFacade} from "@hashgraph/smart-contracts/contracts/system-contracts/hedera-schedule-service/IHRC1215ScheduleFacade.sol";

contract ScheduleManager is HederaScheduleService {
    error FailToDeleteSchedule();

    // Option 1: Internal helper (inheriting HederaScheduleService)
    function deleteScheduleExample(address scheduleAddr) external {
        int64 rc = deleteSchedule(scheduleAddr);
        if (rc != HederaResponseCodes.SUCCESS) {
            revert FailToDeleteSchedule();
        }
    }

    // Option 2: Redirect — call deleteSchedule() on the schedule's address
    // (works for contracts and EOAs)
    function deleteScheduleProxy(address scheduleAddr) external {
        int64 rc = IHRC1215ScheduleFacade(scheduleAddr).deleteSchedule();
        if (rc != HederaResponseCodes.SUCCESS) {
            revert FailToDeleteSchedule();
        }
    }
}

费用

• 调度交易费用与 HAPI ScheduleCreate 相同，系统合约使用会加收 20%。
• 费用包括 Gas、存储和共识费用。过期交易不会产生初始调度和签名费用之外的额外费用。

参考资料

• API 参考：references/api.md — 完整函数签名、选择器和使用说明
• HIP-755：调度服务系统合约
• HIP-756：合约定时代币创建
• HIP-1215：通用定时合约调用
• 源代码：hedera-smart-contracts/hedera-schedule-service