Pharmaceutical Cold Chain Monitor Smart Contract

A robust Clarity smart contract for tracking and monitoring temperature-sensitive pharmaceutical shipments on the Stacks blockchain. Ensures drug integrity through automated temperature monitoring, breach detection, and compliance enforcement.

Overview

This smart contract provides a complete cold chain management solution that automatically monitors temperature conditions, records breaches, and quarantines compromised shipments to protect pharmaceutical integrity.

Key Features

🚚 Shipment Management

• Create shipments with customizable temperature ranges
• Track shipment lifecycle (Created → In Transit → Delivered)
• Automatic status updates based on temperature compliance
• Owner and carrier authorization controls

🌡️ Temperature Monitoring

• Real-time temperature and humidity recording
• Geolocation tracking for each reading
• Automatic breach detection when limits exceeded
• Severity classification (1-3) based on deviation magnitude

⚠️ Breach Management

• Automatic breach logging with timestamps
• Classification: "below-min" or "above-max"
• Maintains breach history (up to 50 per shipment)
• Auto-quarantine after 3+ breaches

🔐 Authorization System

• Contract owner controls carrier/monitor authorization
• Role-based access control (Owner, Carrier, Monitor)
• Secure validation of all inputs

Smart Contract Architecture

Data Structures

Shipments Map

• Drug details (name, origin, destination)
• Temperature thresholds (min/max)
• Status tracking and breach counts
• Ownership and carrier information

Temperature Readings Map

• Shipment association
• Temperature and humidity values
• Location and timestamp data
• Monitor identification

Temperature Breaches Map

• Breach details and classification
• Severity levels (1-3)
• Resolution status
• Timestamp tracking

Constants

Status Types

• status-created (u1) - Shipment initialized
• status-in-transit (u2) - Active monitoring
• status-delivered (u3) - Successfully completed
• status-breached (u4) - Temperature violation detected
• status-quarantined (u5) - Multiple breaches, requires review

Error Codes

• err-owner-only (u100) - Unauthorized owner operation
• err-not-found (u101) - Resource doesn't exist
• err-unauthorized (u102) - Insufficient permissions
• err-invalid-temp (u103) - Invalid temperature range
• err-already-exists (u104) - Duplicate resource
• err-shipment-completed (u105) - Operation on completed shipment
• err-invalid-status (u106) - Invalid status transition
• err-breach-exists (u107) - Breach limit exceeded
• err-invalid-input (u108) - Invalid input parameters

Public Functions

Authorization Management

add-authorized-carrier

(add-authorized-carrier (carrier principal))

Authorizes a carrier to transport shipments. Owner only.

add-authorized-monitor

(add-authorized-monitor (monitor principal))

Authorizes a monitor to record temperature readings. Owner only.

remove-authorized-carrier

(remove-authorized-carrier (carrier principal))

Revokes carrier authorization. Owner only.

Shipment Operations

create-shipment

(create-shipment 
  (drug-name (string-ascii 100))
  (origin (string-ascii 100))
  (destination (string-ascii 100))
  (carrier principal)
  (min-temp int)
  (max-temp int))

Creates a new pharmaceutical shipment with specified parameters. Returns shipment ID.

start-shipment

(start-shipment (shipment-id uint))

Transitions shipment to in-transit status. Owner or carrier only.

complete-shipment

(complete-shipment (shipment-id uint))

Marks shipment as delivered. Carrier only.

quarantine-shipment

(quarantine-shipment (shipment-id uint))

Manually quarantines a shipment. Owner or shipment owner only.

Temperature Recording

record-temperature

(record-temperature
  (shipment-id uint)
  (temperature int)
  (humidity uint)
  (location (string-ascii 100)))

Records temperature reading. Automatically detects and logs breaches. Authorized monitors only.

Read-Only Functions

• get-shipment - Retrieve shipment details
• get-reading - Retrieve temperature reading
• get-breach - Retrieve breach information
• get-shipment-breaches - Get all breach IDs for a shipment
• is-carrier-authorized - Check carrier authorization
• is-monitor-authorized - Check monitor authorization
• get-shipment-status - Get current shipment status
• get-total-shipments - Get total number of shipments
• get-total-readings - Get total number of readings
• is-shipment-compliant - Check if shipment meets compliance

Usage Example

1. Setup Authorization

;; Owner authorizes carrier and monitor
(contract-call? .pharma-cold-chain add-authorized-carrier 'SP2CARRIER...)
(contract-call? .pharma-cold-chain add-authorized-monitor 'SP2MONITOR...)

2. Create Shipment

;; Create vaccine shipment requiring 2-8°C
(contract-call? .pharma-cold-chain create-shipment 
  "COVID-19 Vaccine"
  "Manufacturing Plant A"
  "Hospital B"
  'SP2CARRIER...
  2  ;; min temp (°C)
  8) ;; max temp (°C)
;; Returns: (ok u1)

3. Start Transit

(contract-call? .pharma-cold-chain start-shipment u1)

4. Record Temperature

;; Monitor records compliant temperature
(contract-call? .pharma-cold-chain record-temperature 
  u1
  5   ;; temperature (°C)
  u65 ;; humidity (%)
  "Distribution Center")
;; Returns: (ok u1)

;; Recording breach (10°C exceeds max of 8°C)
(contract-call? .pharma-cold-chain record-temperature 
  u1
  10  ;; temperature breach!
  u70
  "Warehouse")
;; Automatically logs breach and updates status

5. Check Compliance

(contract-call? .pharma-cold-chain is-shipment-compliant u1)
;; Returns: (ok true) if fewer than 3 breaches

6. Complete Delivery

(contract-call? .pharma-cold-chain complete-shipment u1)

Automatic Breach Handling

The contract automatically:

1. Detects temperature violations during recording
2. Calculates severity based on deviation:
   • Severity 1: 0-2°C deviation
   • Severity 2: 2-5°C deviation
   • Severity 3: >5°C deviation
3. Records breach with type (below-min/above-max)
4. Quarantines shipment after 3+ breaches

Security Features

✅ Input Validation - All inputs validated before processing
✅ Role-Based Access - Function-level authorization checks
✅ Immutable Audit Trail - All readings timestamped on-chain
✅ Automatic Enforcement - Quarantine triggers on violations
✅ Principal Validation - Prevents invalid address operations

Technical Specifications

• Language: Clarity
• Blockchain: Stacks
• Code Lines: 299
• Max Breaches Per Shipment: 50
• String Limits: 100 characters
• Humidity Range: 0-100%

Compliance & Standards

This contract supports pharmaceutical cold chain compliance including:

• WHO temperature monitoring guidelines
• GDP (Good Distribution Practice) requirements
• CFR Title 21 pharmaceutical storage standards
• Real-time monitoring and documentation

Development

Testing Checklist

• Test authorization workflows
• Test shipment lifecycle transitions
• Test breach detection at boundaries
• Test quarantine triggering
• Test unauthorized access attempts
• Test input validation edge cases

Deployment Notes

• Deploy with contract owner as trusted entity
• Authorize carriers and monitors before operations
• Consider implementing notification system off-chain
• Monitor breach patterns for quality improvements

Use Cases

1. Vaccine Distribution - COVID-19, flu vaccines requiring 2-8°C
2. Biologics Transport - Temperature-sensitive medications
3. Clinical Trial Materials - Strict temperature compliance
4. Blood Products - Critical temperature maintenance
5. Insulin Shipments - Refrigerated pharmaceutical transport

Future Enhancements

• Multi-signature approval for quarantine resolution
• Integration with IoT temperature sensors
• Automated alerts via oracles
• Carbon credits for compliant shipments
• Insurance claim automation on breaches