Enforce strict typing for mining rounds

[HardlyDifficult]

Summary

• Enforce strict canonical format (snake_case) for Validator API mining round schemas
• Remove backwards compatibility fallback chains (?? patterns) for round_number and contract_id
• Make required fields non-optional in Zod schemas
• Update utility functions to use direct field access
• Clean up related strict typing for amulet and contract utilities from prior session

Changes

Schemas (scan-proxy.ts)

• OpenMiningRoundSchema: Made opensAt and round_number required, removed roundNumber and nested round.number alternatives
• IssuingMiningRoundSchema: Made contract_id required, removed nested contract.contract_id fallback

Utility Functions

• mining-rounds.ts: Removed fallback chains, use direct field access
• get-amulets-for-transfer.ts: Strict contract format (from prior session)
• findCreatedEvent.ts: Removed nested structure fallbacks (from prior session)

Tests

• Updated unit tests to use canonical snake_case format
• Removed tests for legacy/backwards-compatible formats

Test plan

• Unit tests pass locally (313 tests)
• CI integration tests pass against LocalNet (test-cn-quickstart.yml)

resolves ENG-513

---

Note

Medium Risk
Moderate risk because it removes backward-compatibility paths; any upstream services still sending legacy/variant shapes will now fail validation or be ignored, potentially breaking mining-round and transfer flows.

Overview
Enforces the Validator API’s canonical snake_case mining-round response shape by making OpenMiningRoundSchema.payload.opensAt/round_number and IssuingMiningRoundSchema.contract_id required, and removing support for alternate/legacy field locations.

Updates mining-round utilities to use direct field access (no fallback chains) and adjusts unit tests accordingly, dropping coverage for legacy formats. Related cleanup tightens ledger contract parsing in getAmuletsForTransfer and findCreatedEventByTemplateId to only accept the canonical JSON API structures.

^{Written by Cursor Bugbot for commit c149926. This will update automatically on new commits. Configure here.}

[claude]

Claude finished @HardlyDifficult's task —— View job

---

Code Review Completed

I've thoroughly reviewed this PR that enforces strict typing for mining rounds. Here's my analysis:

Todo List

• Read and analyze schema changes in scan-proxy.ts
• Review utility function modifications
• Examine test coverage changes
• Check for potential breaking changes
• Assess backwards compatibility removal
• Provide comprehensive feedback

---

Summary

This is a well-executed cleanup PR that removes backwards compatibility fallbacks and enforces canonical snake_case formatting for mining round schemas. The changes are consistent across the codebase and properly tested.

Issues

None identified. The code follows consistent patterns and defensive programming practices.

---

Full Analysis

Positive Aspects

Clean Schema Simplification - The removal of fallback chains (round_number ?? roundNumber ?? round.number) in favor of direct field access makes the code more predictable and easier to maintain.

Consistent Naming Convention - Enforcing snake_case format across all mining round APIs creates better consistency with the Validator API conventions.

Comprehensive Test Updates - All tests have been properly updated to use the canonical format, with good coverage of edge cases like malformed data and missing fields.

Defensive Runtime Validation - The utility functions still include proper error handling for malformed data at runtime, even with strict schemas:

• mining-rounds.ts:62-68 - Gracefully handles invalid opensAt dates
• get-amulets-for-transfer.ts:147-149 - Type guards for contract validation
• findCreatedEvent.ts:27-31 - Safe property access patterns

Type Safety Improvements - Making opensAt and round_number required in OpenMiningRoundSchema and contract_id required in IssuingMiningRoundSchema prevents potential runtime issues.

Code Quality Assessment

Schema Design (scan-proxy.ts:28-44)

• Clean, minimal schemas with required fields properly specified
• Good use of Zod for validation and type inference
• Consistent field naming following API conventions

Utility Function Refactoring

• mining-rounds.ts:21 - Direct field access is more readable than fallback chains
• get-amulets-for-transfer.ts - Maintains robust contract filtering logic
• findCreatedEvent.ts:38-43 - Canonical structure access with proper error handling

Test Coverage

• Tests appropriately updated to match new canonical format
• Maintained edge case coverage (empty data, malformed timestamps, missing fields)
• Good use of helper functions for test data creation

Performance & Security

Performance: The removal of fallback logic actually improves performance by eliminating unnecessary property lookups.

Security: No security concerns identified. The changes maintain proper input validation and error handling.

Breaking Changes Assessment

This is an intentional breaking change that removes backwards compatibility. However:

• The PR clearly documents this as removing backwards compatibility
• The canonical format has been the primary format in use
• The change enforces data consistency across the API surface

---

Recommendation: ✅ Approve - This is a clean, well-tested refactoring that improves code maintainability and enforces consistent data formatting. The removal of backwards compatibility is intentional and properly documented.

---

[Copilot]

Pull request overview

This PR tightens the typing and canonical formats for mining round and contract-related utilities by enforcing snake_case Validator API schemas and removing support for legacy/variant response shapes. It simplifies consumers to rely on a single canonical shape while keeping runtime behavior defensive where needed.

Changes:

• Enforces canonical snake_case mining-round response schemas in scan-proxy.ts and removes fallback chains for alternative field locations.
• Updates mining-round and amulet utilities (mining-rounds.ts, get-amulets-for-transfer.ts, findCreatedEvent.ts) to use strict, canonical shapes only.
• Aligns unit tests with the new canonical formats and drops tests that covered legacy/nested structures.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/clients/validator-api/schemas/api/scan-proxy.ts	Makes mining round Zod schemas strict to the canonical snake_case fields (round_number, contract_id, required opensAt) that upstream utilities now depend on.
src/utils/mining/mining-rounds.ts	Simplifies round-number and contract-id extraction to rely solely on the canonical Validator API schema, and keeps opensAt filtering defensive against malformed timestamps.
src/utils/contracts/findCreatedEvent.ts	Aligns CreatedTreeEventValue with the canonical Ledger JSON API event schema and restricts findCreatedEventByTemplateId to the documented transactionTree.eventsById layout.
src/utils/amulet/get-amulets-for-transfer.ts	Removes legacy contract shape handling, adds focused helpers for amount/owner extraction, and restricts processing to canonical JsActiveContract responses.
test/unit/mining/mining-rounds.test.ts	Updates mining-round tests to use round_number in payloads, treats malformed opensAt as filtered-out, and removes tests for deprecated round-number formats.
test/unit/contracts/findCreatedEvent.test.ts	Drops coverage for the no-longer-supported nested transaction.transactionTree.eventsById shape and keeps tests aligned with the canonical transactionTree.eventsById.
test/unit/amulet/get-amulets-for-transfer.test.ts	Updates helper contracts and expectations to only use the canonical JsActiveContract shape and validates the new amount/owner extraction and sorting behavior (including coupons and numeric amounts).