TLOSTimedWitness.sol - Time-windowed secret release

[igor53627]

Parent Issue

Closes part of #47

Description

Build a time-windowed witness encryption contract where different secrets are revealed at different time periods, or the same secret becomes easier/harder to claim over time.

Use Case

Traditional time-locks are binary (before/after). TLOS enables:

• Multiple secrets with different unlock windows
• Graduated access (early bird vs late)
• Secrets that expire (can't be claimed after deadline)
• Different witnesses valid at different times

Example Flow

Time                             Contract                          Claimers
 |                                  |                                  |
 | T0: deploy(secrets[], windows[]) |                                  |
 |--------------------------------->| 3 secrets, 3 time windows        |
 |                                  |                                  |
 | T1 (window 1):                   |                                  |
 |                                  |<-- claim(code1, puzzle) ---------|
 |                                  | → releases SECRET_1              |
 |                                  |                                  |
 | T2 (window 2):                   |                                  |
 |                                  |<-- claim(code2, puzzle) ---------|
 |                                  | → releases SECRET_2              |
 |                                  |                                  |
 | T3 (window 3):                   |                                  |
 |                                  |<-- claim(code3, puzzle) ---------|
 |                                  | → releases SECRET_3              |
 |                                  |                                  |
 | T4 (expired):                    |                                  |
 |                                  | owner can reclaim unclaimed      |

Key Features

• Multiple secrets with independent time windows
• Window types:
  • AFTER - claimable after timestamp
  • BEFORE - expires at timestamp
  • BETWEEN - only valid in range
• Different codes for different windows
• Optional: same code, different secrets per window
• Unclaimed secret recovery after final expiry

Security Model

• What's hidden: Secrets, which code unlocks which window
• What's public: Time windows, number of secrets
• Guarantee: 2^76 per secret/code pair

Use Cases

• Staged treasure hunts: Clues released over days/weeks
• Vesting with milestones: Different amounts at different times
• Game mechanics: Power-ups available at specific times
• Expiring offers: Discount code only valid this week
• Progressive disclosure: Research results released in phases

Variants to Consider

1. Early bird bonus: Same secret, but early claimers get bonus
2. Decaying reward: Reward decreases over time
3. Rotating codes: Same secret, but valid code changes each period
4. Cascade: Secret N only claimable after N-1 claimed

Acceptance Criteria

• Contract compiles and passes tests
• All window types (AFTER, BEFORE, BETWEEN) tested
• Edge cases: claim at boundary, expired claims
• Multiple independent secrets tested
• Gas benchmark documented

[igor53627]

Time-Windowed Use Cases Analysis

Good Fit (TLOSTimedWitness works well)

Use Case	Description	Why TLOS Works
Staged treasure hunts	Clues released over days/weeks	Multiple secrets with staggered AFTER windows
Early bird rewards	Bonus for claiming before deadline	BEFORE window + higher reward
Expiring promo codes	Discount only valid this week	BETWEEN window, expires after
Game power-ups	Items available at specific times	Time-gated access codes
Progressive disclosure	Research results in phases	Sequential AFTER windows
NFT reveal scheduling	Traits revealed over time	Multiple secrets per collection
Tournament seeds	Random seed revealed at game start	AFTER tournament begins
Subscription content	Weekly content unlocks	Recurring BETWEEN windows
Flash sales	1-hour window to claim deal	Tight BETWEEN window
Vesting milestones	Different amounts at different times	Multiple secrets with increasing AFTER times

Not Good Fit

Use Case	Problem
Sub-minute precision	Block timestamps have ~12s granularity
Recurring/infinite windows	Contract is one-time; need redeployment
High-volume redemptions	1.3M gas per claim; not for mass distribution
Long-term (years) time locks	Puzzle security may degrade; not recommended

Window Type Semantics

Type	Condition	Example
AFTER	block.timestamp >= start	"Claimable after Jan 1"
BEFORE	block.timestamp < end	"Expires Dec 31"
BETWEEN	start <= now < end	"Valid Jan 1-7 only"

Comparison to Alternatives

Aspect	Simple Timelock	Timelock + Hashlock	TLOSTimedWitness
Time conditions	AFTER only	AFTER/BEFORE manual	AFTER/BEFORE/BETWEEN built-in
Secret protection	None (public state)	Hash only (weak for low-entropy)	Puzzle (2^76 per guess)
Multiple stages	Separate contracts	Manual coordination	Native multi-secret support
Gas to unlock	~30-70k	~50-100k	~1.3M per secret

Target Market

Game/NFT developers and event organizers who:

• Want cryptographically interesting timed reveals
• Need expiring access codes with brute-force protection
• Run staged events (hunts, drops, tournaments)

Gas & Feasibility

• Gas cost: ~1.3M per secret reveal + negligible time checks
• Complexity: M (1-3 days) - straightforward time + puzzle logic
• Key edge cases: Boundary conditions at start/end timestamps