####1. Sui Clock 基础知识

为什么要共享时钟？ Sui 的并行执行模型意味着： -不保证区块顺序 → 无法使用区块号/时间戳 -Clock是一个共享对象，提供共识支持的时间

核心结构：

module sui::clock {  
    struct Clock has key {  
        id: UID,  
        timestamp_ms: u64,  
    }  
}  

主要特性： -每2 秒更新一次（可由验证器配置） -毫秒精度（与以太坊的约 12 秒区块相比） -不可变-不能通过合约修改

---

####2. 实际使用模式

####基本时间检查

use sui::clock;  

public entry fn execute_if_ready(  
    clock: &Clock,  
    lock: &mut LockedAsset  
) {  
    assert!(clock.timestamp_ms >= lock.unlock_time, ELocked);  
    // Release assets  
}  

#####截止日期执行

struct Auction has key {  
    id: UID,  
    end_time: u64, // Stored as Clock timestamp  
    highest_bid: u64  
}  

public entry fn bid(  
    auction: &mut Auction,  
    clock: &Clock,  
    bid_amount: u64  
) {  
    assert!(clock.timestamp_ms < auction.end_time, EAuctionEnded);  
    // Process bid  
}  

####限时操作

struct VestingSchedule has key {  
    id: UID,  
    start_time: u64,  
    cliff_duration: u64 // In milliseconds  
}  

public fun claimable_amount(  
    vesting: &VestingSchedule,  
    clock: &Clock  
): u64 {  
    let elapsed = clock.timestamp_ms - vesting.start_time;  
    // Linear vesting math  
}  

---

####3. 高级注意事项

####分片一致性 -所有分片在交易中看到的相同的时钟时间戳 -对于跨分片操作，请&Clock作为共享对象引用传递

####气体优化 -尽可能存储相对时间（例如duration_ms: u64），而不是绝对时间 -Clock跨函数重复使用相同的引用

####错误处理

const MAX_CLOCK_DRIFT_MS: u64 = 3000; // 3s tolerance  

public fun validate_clock(clock: &Clock) {  
    assert!(tx_context::epoch(ctx) == clock.epoch(), EStaleClock);  
    assert!(clock.timestamp_ms <= tx_context::now_ms(ctx) + MAX_CLOCK_DRIFT_MS, EInvalidTime);  
}  

---

####4. 测试策略

####在测试中模拟时钟

#[test_only]  
fun mock_clock(timestamp_ms: u64): Clock {  
    Clock { id: test_scenario::new_object(ctx), timestamp_ms }  
}  

#[test]  
fun test_vesting() {  
    let clock = mock_clock(1000);  
    let vesting = VestingSchedule { start_time: 0, ... };  
    // Test claimable amount at t=1000  
}  

####Epoch 过渡测试

#[test]  
fun test_clock_epoch_change() {  
    let mut scenario = test_scenario::begin(...);  
    // Advance epoch  
    test_scenario::next_epoch(&mut scenario);  
    let clock = test_scenario::take_shared<Clock>(scenario);  
    assert!(clock.epoch() == 1, EEpochError);  
}  

如果你正在研究时间敏感的逻辑，例如Sui Move中的拍卖或归属时间表，那么sui::clock这个模块是你追踪时间的首选方式. Sui 不依赖以太坊或 Solana 等区块时间戳，因为它的目标是确定性执行和并行性. 这就是为什么它使用共享时钟对象的原因，该对象每个检查点更新一次，并为您提供规范的时间来源.

您可以通过使用读取此共享时钟对象（通常传递到入口函数）来与时间进行交互clock.timestamp. 该值大约每秒更新一次，并以秒为单位为您提供当前 UNIX 时间戳. 虽然它不像在 EVM 中那样绑定到每个区块，但对于代币解锁或出价到期等实际用例来说，它足够精确——只是没有微秒级的精度.

在构建基于时间的逻辑时，请务必明确传入 Clock 对象，这样 Move 函数就可以读取该对象，并将时间戳与存储的截止日期进行比较. 为避免僵化的行为，请在比较中使用宽限期或余地 (if current_time > unlock_time + buffer)，并避免依赖精确的秒数.

对于测试，Sui 允许您通过创建带有自定义时间戳的共享对象实例来在单元测试中模拟时钟. 这样，您无需实时即可模拟未来的情况. 只需在#[test]函数中使用设定值手动构造时钟即可.

如果你感到受限，这可能是因为 Sui 如何保护时钟免受检查点之外的变异. 你需要将时间戳作为输入来设计模块，并从官方共享对象中读取它们. 避免创建自己的时间源，因为这会打破决定论.

🔗 了解有关 Sui Clock 模块的更多信息