Introduce the Time Library

[bitzoic]

Description

This PR introduces a comprehensive UNIX time handling library to the Sway standard library, providing essential time manipulation capabilities for smart contracts.

Time operations are fundamental for many smart contract use cases:

• Token vesting schedules
• Auction deadlines
• Time-locked transactions
• Subscription renewals
• Staking periods

Currently, Sway lacks standardized time utilities, forcing developers to:

• Handle time conversions manually
• Implement custom time logic in every contract
• Risk errors in critical time calculations

This library solves these problems with a robust, well-tested time abstraction.

Duration Handling

// Create durations using natural units
let lock_period = Duration::days(90);
let auction_extension = Duration::minutes(15);

// Convert between units
log(lock_period.as_weeks()); // ≈12.857 weeks
log(auction_extension.as_seconds()); // 900 seconds

// Duration arithmetic
let total_lock = lock_period + Duration::weeks(2);

Blockchain Time Operations

// Get current block time
let now = Time::now();

// Create future/past timestamps
let unlock_time = now.add(Duration::days(30));
let vesting_start = now.subtract(Duration::weeks(12));

// Measure time differences
let time_elapsed = now.duration_since(vesting_start).unwrap();

TAI64 ↔ UNIX Conversion

Support for the existing TAI64 timestamp() functionality is maintained.

// Native TAI64 from blockchain
let tai_timestamp = timestamp();

// Convert to UNIX time
let unix_time = Time::from_tai64(tai_timestamp);

// Convert back to TAI64
let converted_tai = unix_time.as_tai64();
assert(tai_timestamp == converted_tai);

Benefits

• Safety: Prevents common time calculation errors
• Accuracy: Properly handles TAI64/UNIX conversion
• Productivity: Reduces boilerplate for time operations
• Consistency: Standardized approach across contracts
• Readability: Natural time unit expressions

Future Extensions

Once support between different types for Add, Subtract, Multiply, etc are implemented, we may be able to do the following:

let now = Time::now();
let future = now + Duration::DAY;

let three_weeks = Duration::WEEK * 3;

Closes #3945

Checklist

• I have linked to any relevant issues.
• I have commented my code, particularly in hard-to-understand areas.
• I have updated the documentation where relevant (API docs, the reference, and the Sway book).
  • If my change requires substantial documentation changes, I have requested support from the DevRel team
• I have added tests that prove my fix is effective or that my feature works.
• I have added (or requested a maintainer to add) the necessary Breaking* or New Feature labels where relevant.
• I have done my best to ensure that my PR adheres to the Fuel Labs Code Review Standards.
• I have requested a review from the relevant team or maintainers.

[DefiCake]

lgtm