[Tutorial] Time and Deadlines in Compact: Block Time, Counters & the Uint<16> Problem

[Olanetsoft]

Type of Content

Tutorial

Summary

Explain the four block-time query functions (blockTimeLt, blockTimeGte, etc.), the Counter.increment() Uint<16> ceiling (max 65,535 per increment), and workarounds for storing timestamps: hours-since-epoch, multiple increments, or splitting into deadline_hi + deadline_lo fields.

Target Audience

Developers

Deliverables

1. Written tutorial (2,500-3,500 words) covering:

   • Four block-time query functions: blockTimeLt, blockTimeGte, etc.
   • Counter.increment() Uint<16> ceiling (max 65,535)
   • Workarounds for storing timestamps
   • Hours-since-epoch pattern
   • Multiple increments pattern
   • Splitting into deadline_hi + deadline_lo fields

2. Working code examples for each workaround

Requirements:

• Follow Midnight's technical style guide
• All code must be tested and functional

Relevant Links

• Midnight Docs: https://docs.midnight.network/getting-started
• Midnight MCP: https://www.npmjs.com/package/midnight-mcp
• Developer Forum: https://forum.midnight.network/
• Discord: https://discord.com/invite/midnightnetwork

Submission Process

This is an Eclipse bounty. Bounties are not first-come, first-served. Anyone can submit. The best valid submission wins.

1. Work on your submission independently.
2. Share your published link in this issue thread.
3. When ready, comment "Ready for review" explicitly.
4. One review cycle: feedback, revision, approve or reject.

Publishing: Dev.to is the default platform for blog posts and tutorials. Some contributions may also go directly into the Midnight docs. Other platforms (Medium, Hashnode, personal blog) work too.

Promotion: Share on X/LinkedIn with #MidnightforDevs and tag @midnightntwrk.

Policies

AI-Generated Content: Submissions are checked for AI content. Substantially AI-generated work will be disqualified.

Code Must Compile: Any Compact code must compile. Non-compiling code means immediate disqualification.

Terms: By submitting, you agree to the Bounty Program Terms. Payouts in NIGHT tokens after KYC via SumSub.

Tier 2 (Medium) - $500-$700 (paid in NIGHT tokens)

[Halo11112222]

Hey! I put together a submission for this bounty.

Tutorial: ~3,100 words covering the full picture — how blockTimeLt/blockTimeGte work, why Counter.increment() caps at Uint<16> (65,535), and three practical workarounds with code examples: hours-since-epoch, split deadline (hi + lo), and counter chains. I also included a section on common pitfalls (disclose requirements, off-by-one with Lt vs Gte, block time vs wall time).

Code repo: Halo11112222/midnight-time-deadlines-tutorial

• contracts/time-deadlines.compact — Compact contract with all three workaround patterns + block-time query demos
• src/time-utils.ts — TypeScript helpers for timestamp/block-height conversion, Uint32 splitting, increment planning
• tests/time.test.ts — test suite covering conversion, split/join round-trips, and increment planning for large values
• tutorial/article.md — the full written tutorial

The contract compiles under Compact 0.30 and demonstrates setDeadlineHours, setDeadlineSplit, and setDeadlineChained circuits alongside earlyBird, latecomer, and withdrawAfter patterns.

I tried to write this from a developer's perspective — explaining why Uint<16> exists (ZK circuit constraints), not just what the limitation is. The comparison table at the end should help people pick the right approach for their use case.

Happy to adjust anything!

Ready for review 🙏

[lunchfang]

👋 Hi there!

I'm interested in working on this task. Before I start, I'd like to confirm a few details:

1. Bounty Amount: Is the bounty still $500?
2. Acceptance Criteria: What exactly needs to be delivered? Any specific requirements?
3. Timeline: Any deadline or preferred completion time?
4. Testing: Are there specific test cases or environments I should use?
5. Payment: What's the preferred payment method once completed?

Please confirm and I'll get started right away! 🚀

---

Automated message from Atlas Bounty Hunter

[lunchfang]

👋 Hi!

I'm interested in working on this task. Before I start, I'd like to confirm a few details:

1. Bounty Amount: Is the bounty still $500?
2. Acceptance Criteria: What exactly needs to be delivered?
3. Timeline: Any deadline?
4. Testing: Any specific test cases?
5. Payment: Preferred payment method?

Please confirm and I'll get started! 🚀

---

Automated from Bounty Engineering Team

[void-ll]

Hi! I'm looking into this issue and plan to submit a PR shortly. I'll update here if I run into any blockers.

[wilsonhoe]

Submission: Time and Deadlines in Compact

I have completed a tutorial covering all the required topics.

Published at: https://gist.github.com/wilsonhoe/a59c6eb387f1193ca4d7f6c06a7b0c64

What is Covered

Written tutorial (2,765 words) with 11 sections:

1. Privacy-First Time — why Midnight does not expose raw timestamps
2. Block Time API — all four comparison functions with reference table
3. The Uint<16> Problem — why Uint<16> cannot hold timestamps (max 65,535 vs ~1.7B)
4. Counter Type — when to use Counter vs Uint<64>
5. Practical Pattern: Timed Auction (complete circuit)
6. Practical Pattern: Escrow with Expiry (complete circuit)
7. Practical Pattern: Multi-Phase Process with Counter (complete circuit)
8. Three Workarounds for Storing Timestamps:
   • Hours-since-epoch (Uint<32>)
   • Multiple increments (Counter)
   • Split fields: deadline_hi + deadline_lo (Uint<16> pair)
9. Testing block time circuits
10. Common pitfalls and solutions
11. Quick reference card

Working code examples (6 files):

• auction.compact — timed auction circuit
• escrow.compact — escrow with expiry
• multiphase.compact — phase progression with Counter
• hours_epoch.compact — hours-since-epoch workaround
• split_deadline.compact — hi+lo split workaround
• tests.compact — test circuits for block time and Counter

Key Design Decisions

• All timestamps use Uint<64> — no Uint<16> for time values
• Every conditional value uses disclose() (mandatory since v0.16)
• Deadlines passed as parameters, not stored in ledger (privacy-preserving)
• Counter used for progression tracking, not time measurement
• Comparison table for workaround trade-offs (precision, cost, complexity)

Ready for review.

[wilsonhoe]

Published: https://dev.to/wilsonhoe/time-and-delines-in-compact-block-time-counters-the-uint-problem-5877

Ready for review

[Tosh94]

Tutorial: Time and Deadlines in Compact: Block Time, Counters, and Practical Workarounds

Link: https://dev.to/tosh2308/time-and-deadlines-in-compact-block-time-counters-and-practical-workarounds-5cln

Covers: blockTimeLt, blockTimeGte, blockTimeGt, blockTimeBetween predicates; Uint<16> counter ceiling (65,535) and workarounds; hours-since-epoch and deadline_hi/deadline_lo patterns; TypeScript indexer block height queries.

[Tosh94]

I wrote a tutorial on time and deadlines in Compact for this bounty.

Article: https://dev.to/tosh2308/time-and-deadlines-in-compact-block-time-counters-and-pr

Covers: blockTimeLt/blockTimeGte/blockTimeBetween functions, Counter.increment() Uint<16> ceiling (65535 max), timestamp workarounds (hours-since-epoch, deadline_hi + deadline_lo split), TypeScript block height querying