Feature/attestation engine paginated health metrics history

[JohnOluB]

Closes #233

Overview

Introduces optional pagination support for health metrics history in the attestation_engine contract.

What needs to be changed

Contract (contracts/attestation_engine/src/lib.rs)

• Add pagination parameters to health metrics history retrieval function:
  • cursor / start key
  • limit (bounded to prevent abuse)
• Update storage access pattern to support ranged reads instead of full history fetch
• Ensure deterministic ordering (e.g. timestamp or sequence-based keys)
• Add validation for:
  • max limit
  • invalid cursors
• Keep feature optional (default behavior should still work without pagination)

Storage Design

• Refactor how health metrics are stored if needed:
  • Ensure keys are iterable (e.g. timestamp-based or indexed)
  • Support efficient slicing for pagination

Security Considerations

• Validate caller permissions where required (require_auth if mutation is involved)
• Prevent DoS via unbounded queries (enforce max limit)
• Ensure no unintended state mutation during read operations
• Confirm no cross-contract side effects

Tests (contracts/attestation_engine/src/tests.rs)

• Add tests for:
  • pagination with valid cursor + limit
  • boundary conditions (empty dataset, last page)
  • invalid cursor handling
  • max limit enforcement
  • deterministic ordering across pages

Documentation

• Add Rustdoc (///) for:
  • new/updated functions
  • pagination params (cursor, limit, return structure)
• Update docs/ if external integrators depend on this:
  • describe pagination usage pattern
  • include example calls

Notes

• No frontend/backend changes included (contracts-only scope)
• Maintains backward compatibility where pagination is not used

Testing

• Run:
  cargo test -p attestation_engine --target wasm32v1-none --release

• Ensure ≥95% coverage on modified logic