⚡ Bolt: Optimized Blockchain for Field Officer Visits

.jules/bolt.md

@@ -61,3 +61,7 @@
 ## 2025-02-13 - API Route Prefix Consistency
 **Learning:** Inconsistent application of `/api` prefixes between `main.py` router mounting and test suite request paths can lead to 404 errors during testing, even if the logic is correct. This is especially prevalent when multiple agents work on the same codebase with different assumptions about global prefixes.
 **Action:** Always verify that `app.include_router` in `backend/main.py` uses `prefix="/api"` if the test suite (e.g., `tests/test_blockchain.py`) expects it. If a router is mounted without a prefix, ensure tests are updated or the prefix is added to `main.py` to maintain repository-wide consistency.
+
+## 2026-02-14 - O(1) Blockchain Chaining & Cache Optimization
+**Learning:** implementing cryptographic chaining (blockchain) for high-frequency records like field officer visits can introduce latency if the previous hash is fetched via a database scan on every creation. While `order_by(id.desc()).first()` is an indexed lookup, maintaining a thread-safe cache for the last hash further eliminates DB roundtrips. However, the cache must be carefully implemented to avoid redundant "verification" queries that negate the performance gain.
+**Action:** Use a `ThreadSafeCache` to store the last record's hash and ID. On creation, check the cache first. Only on cache miss (or initialization), perform a projected database lookup (`db.query(Model.id, Model.hash)`). Ensure the cache `max_size` accounts for all keys used (e.g., hash and ID) to prevent constant eviction.

backend/cache.py

@@ -175,4 +175,5 @@ def invalidate(self):
 user_upload_cache = ThreadSafeCache(ttl=3600, max_size=1000)  # 1 hour TTL for upload limits
 blockchain_last_hash_cache = ThreadSafeCache(ttl=3600, max_size=1)
 grievance_last_hash_cache = ThreadSafeCache(ttl=3600, max_size=1)
+visit_last_hash_cache = ThreadSafeCache(ttl=3600, max_size=2)
 user_issues_cache = ThreadSafeCache(ttl=300, max_size=50) # 5 minutes TTL

backend/geofencing_service.py

@@ -90,15 +90,17 @@ def is_within_geofence(
     return within_fence, distance
 
 
-def generate_visit_hash(visit_data: dict) -> str:
+def generate_visit_hash(visit_data: dict, prev_hash: str = "") -> str:
     """
     Generate a tamper-resistant HMAC hash for visit data (blockchain-like integrity).
 
     Uses HMAC-SHA256 with server secret to prevent forgery.
     Normalizes datetime to ISO format for deterministic hashing.
+    Supports chaining by including the previous record's hash.
 
     Args:
         visit_data: Dictionary containing visit information
+        prev_hash: Hash of the previous visit record for chaining
 
     Returns:
         HMAC-SHA256 hash of visit data
@@ -111,14 +113,15 @@ def generate_visit_hash(visit_data: dict) -> str:
         else:
             check_in_time_str = str(check_in_time) if check_in_time else ""
 
-        # Create a deterministic string from visit data
+        # Create a deterministic string from visit data including the previous hash
         data_string = (
             f"{visit_data.get('issue_id')}"
             f"{visit_data.get('officer_email')}"
             f"{visit_data.get('check_in_latitude')}"
             f"{visit_data.get('check_in_longitude')}"
             f"{check_in_time_str}"
             f"{visit_data.get('visit_notes', '')}"
+            f"{prev_hash}"
         )
 
         # Generate HMAC-SHA256 hash for tamper-resistance
@@ -137,19 +140,20 @@ def generate_visit_hash(visit_data: dict) -> str:
         return ""
 
 
-def verify_visit_integrity(visit_data: dict, stored_hash: str) -> bool:
+def verify_visit_integrity(visit_data: dict, stored_hash: str, prev_hash: str = "") -> bool:
     """
     Verify the integrity of visit data against stored hash.
 
     Args:
         visit_data: Dictionary containing visit information
         stored_hash: Previously stored hash
+        prev_hash: Previous record hash for chained verification
 
     Returns:
         True if data is unmodified, False otherwise
     """
     try:
-        computed_hash = generate_visit_hash(visit_data)
+        computed_hash = generate_visit_hash(visit_data, prev_hash=prev_hash)
         is_valid = computed_hash == stored_hash
 
         if not is_valid:

backend/init_db.py

@@ -199,6 +199,13 @@ def index_exists(table, index_name):
                 if not index_exists("field_officer_visits", "ix_field_officer_visits_check_in_time"):
                     conn.execute(text("CREATE INDEX IF NOT EXISTS ix_field_officer_visits_check_in_time ON field_officer_visits (check_in_time)"))
 
+                if not column_exists("field_officer_visits", "previous_visit_hash"):
+                    conn.execute(text("ALTER TABLE field_officer_visits ADD COLUMN previous_visit_hash VARCHAR"))
+                    logger.info("Added previous_visit_hash column to field_officer_visits")
+
+                if not index_exists("field_officer_visits", "ix_field_officer_visits_previous_visit_hash"):
+                    conn.execute(text("CREATE INDEX IF NOT EXISTS ix_field_officer_visits_previous_visit_hash ON field_officer_visits (previous_visit_hash)"))
+
             logger.info("Database migration check completed successfully.")
 
     except Exception as e:

backend/models.py

@@ -253,6 +253,7 @@ class FieldOfficerVisit(Base):
 
     # Immutability hash (blockchain-like integrity)
     visit_hash = Column(String, nullable=True)  # Hash of visit data for integrity verification
+    previous_visit_hash = Column(String, nullable=True, index=True) # Linked hash for O(1) verification
 
     # Metadata
     created_at = Column(DateTime, default=lambda: datetime.datetime.now(datetime.timezone.utc))

backend/routers/field_officer.py

@@ -27,9 +27,12 @@
 from backend.geofencing_service import (
     is_within_geofence,
     generate_visit_hash,
+    verify_visit_integrity,
     calculate_visit_metrics,
     get_geofencing_service
 )
+from backend.cache import visit_last_hash_cache
+from backend.schemas import BlockchainVerificationResponse
 
 logger = logging.getLogger(__name__)
 
@@ -58,6 +61,7 @@ def officer_check_in(request: OfficerCheckInRequest, db: Session = Depends(get_d
     - **geofence_radius_meters**: Acceptable distance from site (default: 100m)
 
     **Geo-Fencing**: Automatically verifies if officer is within acceptable radius of issue location
+    **Blockchain Chaining**: Cryptographically links this visit to the previous one for immutability
     """
     try:
         # Validate issue exists
@@ -95,6 +99,22 @@ def officer_check_in(request: OfficerCheckInRequest, db: Session = Depends(get_d
         # Create visit record
         check_in_time = datetime.now(timezone.utc)
 
+        # Blockchain Chaining Logic
+        # Use thread-safe cache to eliminate database lookups for the previous hash
+        prev_hash = visit_last_hash_cache.get("last_hash")
+
+        if prev_hash is None:
+            # Cache miss: fetch only the last hash and ID from DB
+            # Optimization: Use column projection to avoid full model loading
+            last_visit = db.query(FieldOfficerVisit.id, FieldOfficerVisit.visit_hash).order_by(FieldOfficerVisit.id.desc()).first()
+            if last_visit:
+                prev_hash = last_visit[1] or ""
+                visit_last_hash_cache.set(data=prev_hash, key="last_hash")
+                visit_last_hash_cache.set(data=last_visit[0], key="last_id")
+            else:
+                prev_hash = ""
+                visit_last_hash_cache.set(data=prev_hash, key="last_hash")
+
         visit_data = {
             'issue_id': request.issue_id,
             'officer_email': request.officer_email,
@@ -104,8 +124,8 @@ def officer_check_in(request: OfficerCheckInRequest, db: Session = Depends(get_d
             'visit_notes': request.visit_notes or ''
         }
 
-        # Generate immutable hash
-        visit_hash = generate_visit_hash(visit_data)
+        # Generate immutable hash with chaining
+        visit_hash = generate_visit_hash(visit_data, prev_hash=prev_hash)
 
         new_visit = FieldOfficerVisit(
             issue_id=request.issue_id,
@@ -123,13 +143,18 @@ def officer_check_in(request: OfficerCheckInRequest, db: Session = Depends(get_d
             visit_notes=request.visit_notes,
             status='checked_in',
             visit_hash=visit_hash,
+            previous_visit_hash=prev_hash,
             is_public=True
         )
 
         db.add(new_visit)
         db.commit()
         db.refresh(new_visit)
 
+        # Update cache after successful commit
+        visit_last_hash_cache.set(data=visit_hash, key="last_hash")
+        visit_last_hash_cache.set(data=new_visit.id, key="last_id")
+
         logger.info(
             f"Officer {request.officer_name} checked in at issue {request.issue_id}. "
             f"Distance: {distance:.2f}m, Within fence: {within_fence}"
@@ -155,6 +180,8 @@ def officer_check_in(request: OfficerCheckInRequest, db: Session = Depends(get_d
             status=new_visit.status,
             verified_by=new_visit.verified_by,
             verified_at=new_visit.verified_at,
+            visit_hash=new_visit.visit_hash,
+            previous_visit_hash=new_visit.previous_visit_hash,
             is_public=new_visit.is_public,
             created_at=new_visit.created_at
         )
@@ -230,6 +257,8 @@ def officer_check_out(request: OfficerCheckOutRequest, db: Session = Depends(get
             status=visit.status,
             verified_by=visit.verified_by,
             verified_at=visit.verified_at,
+            visit_hash=visit.visit_hash,
+            previous_visit_hash=visit.previous_visit_hash,
             is_public=visit.is_public,
             created_at=visit.created_at
         )
@@ -445,6 +474,86 @@ def get_visit_statistics(db: Session = Depends(get_db)):
         raise HTTPException(status_code=500, detail="Failed to calculate statistics")
 
 
+@router.get("/field-officer/visit/{visit_id}/blockchain-verify", response_model=BlockchainVerificationResponse)
+def verify_visit_blockchain(visit_id: int, db: Session = Depends(get_db)):
+    """
+    Verify the cryptographic integrity of a field officer visit using O(1) blockchain verification.
+
+    Checks if the stored visit_hash correctly seals the record data and links to the previous record.
+    """
+    try:
+        # Fetch visit data including the link to previous hash
+        visit = db.query(
+            FieldOfficerVisit.id,
+            FieldOfficerVisit.issue_id,
+            FieldOfficerVisit.officer_email,
+            FieldOfficerVisit.check_in_latitude,
+            FieldOfficerVisit.check_in_longitude,
+            FieldOfficerVisit.check_in_time,
+            FieldOfficerVisit.visit_notes,
+            FieldOfficerVisit.visit_hash,
+            FieldOfficerVisit.previous_visit_hash
+        ).filter(FieldOfficerVisit.id == visit_id).first()
+
+        if not visit:
+            raise HTTPException(status_code=404, detail=f"Visit {visit_id} not found")
+
+        # Prepare data for hash recomputation
+        # NOTE: When recomputing the hash, we must ensure the check_in_time format
+        # matches exactly what was used during creation (isoformat).
+        # SQLite returns naive datetime objects, so we need to ensure consistency.
+        check_in_time_str = ""
+        if visit.check_in_time:
+            # If it's a datetime object, convert to ISO format string
+            # We use the same logic as in create_issue and create_grievance
+            if visit.check_in_time.tzinfo is None:
+                # Naive datetime from SQLite, assume UTC
+                check_in_time_str = visit.check_in_time.replace(tzinfo=timezone.utc).isoformat()
+            else:
+                check_in_time_str = visit.check_in_time.isoformat()
+
+        visit_data = {
+            'issue_id': visit.issue_id,
+            'officer_email': visit.officer_email,
+            'check_in_latitude': visit.check_in_latitude,
+            'check_in_longitude': visit.check_in_longitude,
+            'check_in_time': check_in_time_str,
+            'visit_notes': visit.visit_notes or ''
+        }
+
+        # Determine previous hash (O(1) from stored column)
+        prev_hash = visit.previous_visit_hash or ""
+
+        # Verify integrity using the service helper for O(1) chained verification
+        is_valid = verify_visit_integrity(
+            visit_data,
+            visit.visit_hash or "",
+            prev_hash=visit.previous_visit_hash or ""
+        )
+
+        if visit.visit_hash is None:
+            message = "No integrity hash present for this visit record."
+        else:
+            message = (
+                "Integrity verified. This visit record is cryptographically sealed and part of a secure chain."
+                if is_valid
+                else "Integrity check failed! The visit data or chain link has been tampered with."
+            )
+
+        return BlockchainVerificationResponse(
+            is_valid=is_valid,
+            current_hash=visit.visit_hash,
+            computed_hash=generate_visit_hash(visit_data, prev_hash=visit.previous_visit_hash or ""),
+            message=message
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error verifying visit blockchain for {visit_id}: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail="Failed to verify visit integrity")
+
+
 @router.post("/field-officer/visit/{visit_id}/verify")
 def verify_visit(
     visit_id: int,

backend/schemas.py

@@ -515,6 +515,8 @@ class FieldOfficerVisitResponse(BaseModel):
     status: str = Field(..., description="Visit status")
     verified_by: Optional[str] = Field(None, description="Verified by")
     verified_at: Optional[datetime] = Field(None, description="Verification timestamp")
+    visit_hash: Optional[str] = Field(None, description="Integrity hash")
+    previous_visit_hash: Optional[str] = Field(None, description="Previous visit hash")
     is_public: bool = Field(..., description="Public visibility")
     created_at: datetime = Field(..., description="Creation timestamp")