contracts

Decentralized Healthcare System on Stellar

A blockchain-based healthcare management system built with Soroban smart contracts on the Stellar network, enabling secure, transparent, and efficient healthcare data management.

Overview

This decentralized healthcare system leverages Stellar's Soroban smart contracts to provide a trustless, HIPAA-compliant solution for managing electronic health records (EHR), patient data, medical appointments, and healthcare provider interactions. The system ensures data privacy, interoperability, and patient sovereignty over personal health information.

Key Features

• Patient Data Sovereignty: Patients maintain complete control over their health records with cryptographic access management
• Secure Health Records: Encrypted storage of medical records with granular permission controls
• Provider Verification: Blockchain-based credential verification for healthcare providers
• Appointment Management: Decentralized scheduling and management of medical appointments
• Medical History Tracking: Immutable audit trail of all medical interactions and treatments
• Insurance Integration: Smart contract-based claims processing and verification
• Prescription Management: Secure digital prescription issuance and tracking
• Consent Management: Patient-controlled data sharing with healthcare providers and institutions

Architecture

Smart Contracts

The system is organised as a Cargo workspace. Each contract lives in its own crate under contracts/:

Crate	Description
contracts/patient-registry	Patient identity and profile management
contracts/provider-registry	Healthcare provider credentials and verification
contracts/health-records	Electronic health record storage and access control
contracts/doctor-registry	Doctor registration and credential management
contracts/hospital-registry	Hospital registration and configuration
contracts/insurer-registry	Insurance provider registry
contracts/prescription-management	Digital prescription issuance and pharmacy verification
contracts/medical-claims	Automated claims processing and settlement
contracts/access-control	Patient consent and data-sharing permissions
contracts/allergy-management	Allergy record management
contracts/allergy-tracking	Real-time allergy tracking and alerting
contracts/care-plan	Patient care-plan management
contracts/clinical-guideline	Clinical guideline publication
contracts/clinical-trial	Clinical trial enrollment and tracking
contracts/dental-records	Dental record storage
contracts/emergency-medical-info	Emergency medical information registry
contracts/financial-records	Patient financial and billing records
contracts/hai-tracking	Hospital-acquired infection tracking
contracts/healthcare-analytics	On-chain analytics aggregation
contracts/healthcare-credentialing	Provider credentialing workflows
contracts/hospital-discharge-management	Discharge planning and management
contracts/imaging-radiology	Medical imaging and radiology record management
contracts/immunization-registry	Immunization records
contracts/lab-management	Lab test ordering and result management
contracts/medical-device-tracking	Medical device inventory and tracking
contracts/mental-health	Mental health record management
contracts/multisig-governance	Multi-signature governance for admin actions
contracts/nutrition-care-management	Nutrition and dietary care management
contracts/pacs-integration	PACS system integration
contracts/patient-vitals	Patient vital-signs tracking
contracts/prenatal-pediatric	Prenatal and pediatric care records
contracts/prior-authorization	Insurance prior-authorization workflows
contracts/referral	Patient referral management
contracts/rehabilitation-services	Rehabilitation program tracking
contracts/telemedicine	Telemedicine session management
contracts/upgrade-governance	Contract upgrade governance
contracts/zk-eligibility-verifier	Zero-knowledge eligibility verification

Architecture Decision Records

Design rationale for key architectural and security decisions is documented in docs/adr/.

• docs/adr/ADR-001.md — Why Soroban/Stellar vs other blockchain platforms
• docs/adr/ADR-002.md — Storage TTL retention class design (Critical/Operational/Ephemeral)
• docs/adr/ADR-003.md — Hash-based privacy for sensitive fields
• docs/adr/ADR-004.md — Multi-sig governance threshold design
• docs/adr/ADR-005.md — Actor verification caching strategy in shared module
• docs/adr/ADR-006.md — Why no-std with WASM target

Technology Stack

• Blockchain: Stellar Network
• Smart Contracts: Soroban (Rust-based)
• Development Framework: Soroban SDK
• Testing: Soroban Test Framework
• Deployment: Stellar CLI

Prerequisites

Before you begin, ensure you have the following installed:

• Rust (1.74.0 or later)
• Soroban CLI
• Stellar CLI
• Node.js (18.x or later) - for frontend integration
• Docker (optional, for local Stellar network)

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Soroban CLI
cargo install --locked soroban-cli

# Install Stellar CLI
cargo install --locked stellar-cli

Installation

1. Clone the repository:

git clone https://github.com/KingFRANKHOOD/contracts.git
cd contracts

Or via SSH:

git clone git@github.com:KingFRANKHOOD/contracts.git
cd contracts

2. Install dependencies:

cargo build

3. Configure your environment:

cp .env.example .env
# Edit .env with your configuration

Configuration

Create a .env file in the root directory:

STELLAR_NETWORK=testnet
SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
ADMIN_SECRET_KEY=your_secret_key_here
CONTRACT_WASM_HASH=your_contract_hash

Deployment

Local Development Network

1. Start a local Stellar network:

stellar network start local

2. Build the smart contracts:

soroban contract build

3. Deploy to local network:

soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/patient_registry.wasm \
  --source admin \
  --network local

Testnet Deployment

Automated Full Deployment (Recommended)

Deploy all contracts in dependency order with a single command:

./scripts/deploy_all.sh \
  --network testnet \
  --identity my-testnet-identity \
  --admin-address <ADMIN_ADDRESS>

This script will:

• Build all contracts in the workspace
• Optimize WASM artifacts for size/gas efficiency
• Deploy in dependency order (registries → feature contracts)
• Record contract IDs to deployments/testnet.json
• Skip re-deployment of existing contracts (idempotent)

Options:

--network <name>           Network name (default: testnet)
--identity <name>          Stellar CLI identity (default: from env)
--admin-address <address>  Admin address for contract initialization
--dry-run                  Show deployment plan without executing
--skip-build               Use existing WASM artifacts
--skip-optimize            Skip WASM optimization
--skip-init                Don't initialize contracts after deployment
--cli-bin <binary>         Stellar CLI binary (default: stellar)

Manual Single Contract Deployment

1. Build optimized contracts:

stellar contract build --target wasm32-unknown-unknown --release
stellar contract optimize --wasm target/wasm32-unknown-unknown/release/patient_registry.wasm

2. Deploy to Stellar Testnet:

stellar contract deploy \
  --wasm target/wasm32-unknown-unknown/release/patient_registry.optimized.wasm \
  --source admin \
  --network testnet

3. Initialize contracts:

stellar contract invoke \
  --id <CONTRACT_ID> \
  --source admin \
  --network testnet \
  -- initialize \
  --admin <ADMIN_ADDRESS>

Testnet Deployment Status

Current testnet contract IDs are recorded in deployments/testnet.json:

{
  "_network": "testnet",
  "_status": "COMPLETE",
  "provider-registry": "CXXXXXX...",
  "patient-registry": "CXXXXXX...",
  "referral": "CXXXXXX...",
  "lab-management": "CXXXXXX..."
}

Mainnet Deployment & TTL Management

TTL Extension for Mainnet Contracts

Soroban contracts on Stellar Mainnet require periodic TTL (Time-To-Live) extension to prevent expiration and data loss. The system automatically extends TTLs every 90 days via a scheduled GitHub Actions workflow.

Manual TTL Extension:

./scripts/extend-ttls.sh \
  --network mainnet \
  --identity my-mainnet-identity \
  --ledgers-to-extend 535680

This extends the instance storage TTL for all deployed contracts by ~1 year. TTL parameters:

• 535680 ledgers = ~1 year at 5 seconds per ledger
• Recommended to extend every 90 days (leaves 9 months buffer)
• Critical threshold: 86400 ledgers (~1 day) remaining

Options:

--network <name>              Network name (mainnet, testnet)
--identity <name>             Stellar CLI identity (required)
--ledgers-to-extend <count>   Ledgers to extend (default: 535680)
--critical-threshold <ledgers> Alert if below threshold (default: 86400)
--dry-run                     Preview extensions without executing
--cli-bin <binary>            Stellar CLI binary (default: stellar)

Automated TTL Extension (GitHub Actions):

A scheduled workflow (.github/workflows/extend-ttls.yml) runs every 90 days to automatically extend TTLs for mainnet contracts. This ensures production contracts never expire.

To trigger manually:

gh workflow run extend-ttls.yml -f network=mainnet

Important: Failing to extend TTLs will cause contracts to expire, making them inaccessible and data permanently lost. Monitor TTL status in CI/CD logs.

Upgrade Guide

A step-by-step upgrade workflow is available in docs/upgrade-guide.md, including schema migration, multi-sig governance submission, rollback procedures, and testnet dry run examples.

Usage

Patient Registration

soroban contract invoke \
  --id <PATIENT_REGISTRY_CONTRACT> \
  --source patient \
  --network testnet \
  -- register_patient \
  --patient_id "P12345" \
  --name "John Doe" \
  --dob "1990-01-01" \
  --encrypted_data <ENCRYPTED_HEALTH_DATA>

Provider Verification

soroban contract invoke \
  --id <PROVIDER_REGISTRY_CONTRACT> \
  --source provider \
  --network testnet \
  -- register_provider \
  --provider_id "DR001" \
  --name "Dr. Jane Smith" \
  --specialty "Cardiology" \
  --credentials <CREDENTIAL_HASH>

Hospital Configuration

soroban contract invoke \
  --id <HOSPITAL_REGISTRY_CONTRACT> \
  --source hospital \
  --network testnet \
  -- register_hospital \
  --wallet <HOSPITAL_WALLET> \
  --name "Regional Medical Center" \
  --location "789 Pine Rd" \
  --metadata "Accredited, trauma level II"

soroban contract invoke \
  --id <HOSPITAL_REGISTRY_CONTRACT> \
  --source hospital \
  --network testnet \
  -- set_hospital_config \
  --wallet <HOSPITAL_WALLET> \
  --config <CONFIG_XDR>

Grant Data Access

soroban contract invoke \
  --id <CONSENT_MANAGER_CONTRACT> \
  --source patient \
  --network testnet \
  -- grant_access \
  --patient_id "P12345" \
  --provider_id "DR001" \
  --duration_days 30 \
  --access_level "read"

Testing

Run the complete test suite:

cargo test

Run specific test modules:

cargo test patient_registry
cargo test health_records

Run integration tests:

cargo test --test integration_tests