feat(master): send the completed epoch's chain time to challenges

[Mathis (echobt)]

Problem and behavior

OpenType is switching from finite FIFO credits (exhausted in production: every recent epoch burned OpenType's 70 %) to a continuous champion reward: 100 % for 36 h after a certified crown, then a 36 h half-life (OpentypeAI/challenge#8). Pricing needs the epoch's chain time, not the time of the HTTP request, which differs for delayed or replayed epochs.

Previous behavior: get_weights?epoch=N only.

New behavior:

• BittensorChain.snapshot reads Timestamp.Now at the pinned end-block hash (validated integer ms, floored to seconds) into optional ChainSnapshot.timestamp_seconds.
• EpochEmitter passes it to ChallengeClient.weights(..., epoch_at=), sent as the authenticated query epoch_at.
• Algorithm 3 with trusted OpenType: missing/invalid timestamp postpones emission before any leaf is replaced or the epoch sealed (no signed NoScore, no burned epoch). Bounty/proof-only configurations are unaffected. No wall-clock or estimated block-time fallback.
• Validators: timestamp unavailable leaves snapshots unchanged; reorg detection unchanged.

Validation

• Ruff format and lint
• Mypy (84 files)
• Offline test suite: 1138 passed (also via pre-push hook)
• scripts/check_repo.py --final
• Deployment contracts when deploy files changed (none changed)
• Wheel build when packaging/runtime files changed (none changed)

Public contract

• Miner documentation is updated, or the public API did not change (challenge contract documented in docs/CHALLENGES.md)
• No challenge content, credential, floating production image, or invented digest was added
• Frozen protocol specifications and BASE_*/domain compatibility remain intact

Review

CodeRabbit replaces Greptile for this repository.

Risk

• Emission: OpenType epochs wait for a valid chain timestamp; a node without historical Timestamp.Now stalls sealing (logged completed epoch timestamp unavailable) rather than burning.
• Signatures/protocol: unchanged. Validators need no upgrade.
• Rollback: revert; containers ignore the extra query parameter.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Challenge scoring can now use the timestamp recorded for the completed epoch, supporting time-based scoring against historical data.
  • Existing challenge configurations continue to work without an epoch timestamp.
• Bug Fixes
  • For affected scoring configurations, epoch emission is postponed when a valid timestamp is unavailable. The epoch’s results remain unchanged until emission can proceed, preventing incomplete results from being sealed.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 010b58af-a07f-4cdf-8390-3beedc487213

📥 Commits

Reviewing files that changed from the base of the PR and between 540b4fe and a4f3ea4.

📒 Files selected for processing (8)

• docs/CHALLENGES.md
• src/cortex/challenges/client.py
• src/cortex/master.py
• src/cortex/validator/chain.py
• src/cortex/validator/service.py
• tests/challenges/test_contract.py
• tests/test_master.py
• tests/validator/test_chain.py

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

The validator now records an optional timestamp from the pinned block. The master can pass that time to container challenge requests. Algorithm 3 epochs with an OpenType challenge require valid time before scoring and sealing.

Changes

Historical epoch timestamp scoring

Layer / File(s)	Summary
Capture pinned block timestamps src/cortex/validator/service.py, src/cortex/validator/chain.py, tests/validator/test_chain.py	ChainSnapshot carries an optional timestamp in seconds. The chain reads and validates the timestamp from the pinned block. Tests cover conversion, invalid values, RPC failures, and reorganizations.
Send optional epoch time to challenge endpoints src/cortex/challenges/client.py, tests/challenges/test_contract.py	ChallengeClient.weights accepts a positive unsigned 64-bit epoch_at and includes it in request parameters when provided. Tests cover requests with and without the parameter, headers, and invalid values.
Gate scoring and sealing on required epoch time src/cortex/master.py, tests/test_master.py, docs/CHALLENGES.md	The master passes valid snapshot time to challenge scoring. Algorithm 3 epochs with an OpenType challenge fail with a 503 when time is unavailable. Tests cover postponed and resumed emission, timestamp forwarding, and bounty-only emission without time. The documentation describes the parameter and behavior.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant BittensorChain
  participant EpochEmitter
  participant ChallengeClient
  participant ContainerChallenge
  BittensorChain-->>EpochEmitter: Completed snapshot with optional timestamp
  alt Algorithm 3 includes OpenType and timestamp is unavailable
    EpochEmitter-->>EpochEmitter: Raise 503 before scoring or sealing
  else Timestamp is available or not required
    EpochEmitter->>ChallengeClient: Request weights with epoch and optional epoch_at
    ChallengeClient->>ContainerChallenge: GET weights with request parameters
    ContainerChallenge-->>ChallengeClient: Return challenge weights
    ChallengeClient-->>EpochEmitter: Return weights
  end

Loading

Merge Risk: ⚪ Minimal · up to a4f3e

No actionable issue is established for the timestamp-scoring change; it is mergeable after normal checks.

Security Architecture Review

Security architecture risk: 🟡 Moderate · up to a4f3e

The new timestamp check prevents an epoch from being sealed with scores based on missing historical time. It also makes reward issuance depend on historical timestamp availability. A separate compatibility risk remains: a challenge that rejects the new request parameter could have its scores recorded as unavailable rather than causing emission to wait. Production compatibility is not established by the available tests.

Retained concerns

• Medium · reliability · inferred: A historical timestamp query that remains unavailable leaves the first affected OpenType epoch pending and blocks emission of later pending epochs. This is an intentional fail-closed choice, but historical-query support is now an availability dependency for the emission queue.
• Medium · security · inferred: Available epoch time is sent to all non-proof challenges, but only the Algorithm 3 OpenType missing-time case postpones emission. If a challenge rejects or cannot process the new parameter, its scoring error becomes signed NoScore leaves and the epoch can be sealed. The actual deployed-handler response is unverified.

Security review details

Security Blast Radius

• inferred — The availability effect can extend beyond one epoch: a pending OpenType epoch that cannot obtain historical time stops this master's ordered emission loop before later pending epochs are processed. The new parameter does not itself select a destination or expand the participant set.

Security Findings and Attack Paths

• inferred — A challenge handler that rejects epoch_at can produce a scoring exception; the master catches that exception, signs NoScore outcomes, and can seal the epoch. This is a conditional contract-mismatch path, not evidence that a deployed handler rejects the parameter.

Trust Boundaries and Controls

• observed — The outbound request still uses the registry-derived container URL and fixed internal endpoint with per-challenge authentication. The response remains bounded and parsed against the requested challenge slug and epoch; epoch_at changes scoring input, not those identity checks.

Resilience and Maintainability Implications

• observed — Missing chain time fails closed before signing leaves, while challenge scoring exceptions remain fail-to-NoScore. The former is covered by a recovery test; the latter makes downstream contract compatibility consequential to the sealed reward result.

Hardening Proposals

• proposed — Before enabling time-dependent scoring, verify that the production chain endpoint serves pinned historical timestamps and that affected challenge handlers accept epoch_at; consider distinguishing request-contract failure from an intentional sealable NoScore outcome.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 28 functions across 7 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: sending the completed epoch's chain time from the master to challenge containers.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 28 functions across 7 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

_{Comment @coderabbitai help to get the list of available commands.}