Installation

This guide provides detailed installation and configuration instructions for setting up Salud Health, a privacy-preserving medical records management system built on Aleo blockchain.

System Requirements

Node.js

Version 18 or higherRequired for running the frontend and development tools.

Package Manager

npm or yarnFor managing dependencies.

Browser

Modern BrowserChrome, Firefox, Safari, or Edge (latest versions)

Aleo Wallet

Private KeyFrom Leo Wallet, Shield Wallet, or generated fresh

Project Structure

Understanding the Salud Health project structure:

Salud/
├── Main APP/                    # React frontend application
│   ├── src/
│   │   ├── components/         # React components
│   │   │   ├── layout/        # Header, Sidebar, AppLayout
│   │   │   ├── records/       # Record management components
│   │   │   ├── doctor/        # Doctor-specific components
│   │   │   └── ui/            # Reusable UI components
│   │   ├── contexts/          # React context providers
│   │   ├── pages/             # Route page components
│   │   ├── hooks/             # Custom React hooks
│   │   ├── store/             # Zustand state management
│   │   └── lib/               # Utilities and API clients
│   ├── package.json           # Frontend dependencies
│   └── vite.config.ts         # Vite configuration
├── Salud Health Contract/      # Aleo smart contract
│   ├── src/main.leo           # Leo program source
│   ├── build/                 # Compiled program
│   └── program.json           # Program configuration
├── deprecated_backend/         # Legacy backend (optional)
│   └── server.js              # Node.js API server
└── .env.example               # Environment configuration template

Frontend Installation

Clone the Repository

First, clone the Salud Health repository:

git clone <repository-url>
cd Salud

Navigate to Frontend Directory

The frontend is located in the Main APP directory:

cd "Main APP"

Install Dependencies

Install all required npm packages:

npm install

This will install key dependencies including:

{
  "@provablehq/sdk": "^0.9.15",
  "@provablehq/wasm": "^0.9.15",
  "react": "^18.3.1",
  "react-router-dom": "^7.13.0",
  "zustand": "^5.0.10",
  "framer-motion": "^12.29.0",
  "lucide-react": "^0.563.0"
}

The @provablehq/sdk package provides the core functionality for interacting with the Aleo blockchain.

Configure Environment Variables

Create a .env file in the Main APP directory:

cp ../.env.example .env

Edit the .env file with your configuration:

# Aleo Network Configuration
ALEO_NETWORK=testnet
ALEO_ENDPOINT=https://api.explorer.provable.com/v1

# Program ID (deployed contract)
PROGRAM_ID=salud_health_records_v6.aleo

# Optional: Pre-fill wallet for testing (NEVER commit real keys)
ALEO_PRIVATE_KEY=
ALEO_VIEW_KEY=
ALEO_ADDRESS=

Never commit your .env file to version control. The .gitignore is already configured to exclude it, but always double-check before pushing.

Start Development Server

Launch the Vite development server:

npm run dev

You should see:

VITE v7.2.4  ready in 234 ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose

Open your browser to http://localhost:5173

Aleo Wallet Setup

Salud Health requires an Aleo private key for encrypting medical data. Here’s a detailed explanation and setup guide:

Why Does Salud Require a Private Key?

Unlike typical dApps that use browser wallet extensions, Salud requires direct access to your private key because:

End-to-End Encryption

Your medical records are encrypted client-side using your private key before they leave your browser. This ensures:

Data is encrypted before reaching any server
Only you can decrypt your medical information
Zero-knowledge: even the blockchain can’t read your data
HIPAA-grade privacy protection

Browser wallets (Leo, Shield, etc.) don’t expose private keys for encryption operations, only for signing transactions.

Cryptographic Proof Generation

When sharing records with doctors, Salud generates cryptographic access tokens using:

let access_token: field = BHP256::hash_to_field(AccessTokenInput {
    record_id: medical_record.record_id,
    doctor: doctor,
    patient: self.caller,
    nonce: nonce,
});

This requires direct cryptographic operations not available through standard wallet APIs.

Session-Based Record Management

The application maintains a secure session with the Aleo network to:

Fetch your encrypted records from the blockchain
Monitor access grants and expirations
Track record creation and sharing history

These operations require persistent access to cryptographic functions.

Getting Your Private Key

Leo Wallet
Shield Wallet
Generate New
Aleo SDK

Export from Leo Wallet (Recommended for existing users)

Install Leo Wallet browser extension if you haven’t already
Create or access your existing account
Click your account avatar in the extension
Navigate to Settings → Security & Privacy
Click “Export Private Key”
Enter your wallet password to authenticate
Copy the private key (format: APrivateKey1zkp...)
Store it securely in a password manager

This is the same private key that controls your Aleo credits. Treat it like your bank password.

Generate Fresh Account (Recommended for testing)Open Salud and click “Generate New” on the wallet connect screen. The app will:

Create a new Aleo account using @provablehq/sdk
Display your private key, view key, and address
Automatically connect to the session

Save these credentials:

Private Key: APrivateKey1zkp...
View Key:    AViewKey1...
Address:     aleo1...

You can later import this account into Leo Wallet or Shield Wallet using the same private key.

Generate via Aleo SDK (For developers)If you’re working with the Aleo SDK directly:

import { Account } from '@provablehq/sdk';

// Generate new account
const account = new Account();

console.log('Private Key:', account.privateKey().to_string());
console.log('View Key:', account.viewKey().to_string());
console.log('Address:', account.address().to_string());

Or via command line:

leo account new

Private Key Security Best Practices

Use a Password Manager

Store your private key in a secure password manager like:

1Password
Bitwarden
LastPass
KeePass

Never store it in:

Plain text files
Email
Cloud notes (Google Docs, Notion, etc.)
Screenshots

Separate Testing and Production

Use different accounts for:

Testing: Fresh generated account with no real value
Production: Your main Aleo wallet with actual credits

This limits exposure if test keys are compromised.

Enable Demo Mode for Development

When developing or testing locally, use demo mode to avoid blockchain transactions:

DEMO_MODE=true

In demo mode:

All features work normally
Records stored in localStorage
No real blockchain transactions
No credits required

Smart Contract Deployment (Optional)

If you want to deploy your own instance of the Salud Health contract:

Install Leo CLI

Install the Leo programming language toolchain:

curl -L https://install.leo-lang.org | bash
leo update

Verify installation:

leo --version

Navigate to Contract Directory

cd "Salud Health Contract"

Build the Contract

Compile the Leo program:

leo build

This creates compiled artifacts in the build/ directory.

Deploy to Testnet

Deploy the contract to Aleo testnet:

leo deploy --network testnet

You’ll need:

An Aleo private key with testnet credits
Network connectivity to Aleo testnet

Deployment costs testnet credits. Get free testnet credits from the Aleo Faucet.

Update Frontend Configuration

After deployment, update your frontend .env file with the new program ID:

PROGRAM_ID=your_program_name.aleo

Backend Setup (Optional - Deprecated)

The deprecated backend is optional and not required for core functionality:

Legacy Backend Installation

If you need the backend for API-based operations:

cd deprecated_backend
npm install

Create backend/.env:

PORT=3001
ALEO_API_URL=https://api.explorer.provable.com/v1
PROGRAM_ID=salud_health_records_v6.aleo
DEMO_MODE=false

Start the backend:

npm start

Backend Dependencies:

{
  "express": "^4.18.0",
  "cors": "^2.8.5",
  "dotenv": "^16.0.0",
  "@provablehq/sdk": "^0.9.15"
}

The backend is deprecated. Current frontend connects directly to Aleo blockchain without requiring a backend server.

Production Build

To build Salud Health for production deployment:

Build Frontend

Create an optimized production build:

cd "Main APP"
npm run build

This creates a dist/ directory with optimized static files.

Preview Production Build

Test the production build locally:

npm run preview

This serves the dist/ folder at http://localhost:4173

Deploy Static Files

Deploy the dist/ directory to your hosting provider:Vercel:

vercel deploy

Netlify:

netlify deploy --prod

AWS S3:

aws s3 sync dist/ s3://your-bucket-name

Salud Health is a static single-page application (SPA). Ensure your hosting provider is configured for SPA routing.

Environment Variables Reference

ALEO_NETWORK

string

default:"testnet"

Aleo network to connect to. Options: testnet, mainnet

ALEO_ENDPOINT

string

default:"https://api.explorer.provable.com/v1"

Aleo API endpoint URL for blockchain queries

PROGRAM_ID

string

default:"salud_health_records_v6.aleo"

Deployed smart contract program identifier

ALEO_PRIVATE_KEY

string

Optional: Pre-fill private key for testing (59 characters, starts with APrivateKey1)

Never commit this to version control

ALEO_VIEW_KEY

string

Optional: View key for read-only blockchain queries

ALEO_ADDRESS

string

Optional: Wallet address (starts with aleo1)

DEMO_MODE

boolean

default:"false"

Enable demo mode for testing without blockchain transactions

Verification

Verify your installation is working correctly:

Frontend Loads

✅ Application loads at http://localhost:5173✅ No console errors in browser DevTools

Wallet Connection

✅ Can paste or generate a private key✅ Wallet connects successfully✅ Address displays correctly (format: aleo1...)

Create Test Record

✅ Can open “New Record” modal✅ Form accepts input✅ Record creates successfully on testnet✅ Record appears in dashboard after blockchain confirmation

Troubleshooting

Module not found errors

Clear node_modules and reinstall:

rm -rf node_modules package-lock.json
npm install

Vite build fails

Ensure you’re using Node.js 18+:

node --version

Update if necessary:

nvm install 18
nvm use 18

Cannot connect to Aleo network

Check network connectivity:

curl https://api.explorer.provable.com/v1/testnet/latest/height

If this fails, verify:

Your internet connection
Firewall settings
VPN isn’t blocking Aleo endpoints

Private key validation fails

Ensure your private key:

Starts with APrivateKey1
Is exactly 59 characters
Contains no spaces or line breaks
Is from Aleo network (not Bitcoin, Ethereum, etc.)

TypeScript errors during build

Run type checking:

npm run build

Fix any TypeScript errors reported. Common issues:

Missing type definitions
Incorrect import paths
Version mismatches in @types/* packages

Next Steps

Quick Start

Create your first medical record in 5 minutes

Architecture

Understand how Salud integrates with Aleo

Smart Contract

Explore the Leo contract source code

User Guides

Patient and doctor usage guides

Getting Help

If you encounter issues:

Check the troubleshooting guide
Review the FAQ
Open an issue on GitHub
Join the Aleo Discord

Get Started

Core Features

User Guides

Architecture

System Requirements

Node.js

Package Manager

Browser

Aleo Wallet

Project Structure

Frontend Installation

Aleo Wallet Setup

Why Does Salud Require a Private Key?

Getting Your Private Key

Private Key Security Best Practices

Smart Contract Deployment (Optional)

Backend Setup (Optional - Deprecated)

Production Build

Environment Variables Reference

Verification

Troubleshooting

Next Steps

Quick Start

Architecture

Smart Contract

User Guides

Getting Help

Build docs developers (and LLMs) love

Get Started

Core Features

User Guides

Architecture

​System Requirements

Node.js

Package Manager

Browser

Aleo Wallet

​Project Structure

​Frontend Installation

​Aleo Wallet Setup

​Why Does Salud Require a Private Key?

​Getting Your Private Key

​Private Key Security Best Practices

​Smart Contract Deployment (Optional)

​Backend Setup (Optional - Deprecated)

​Production Build

​Environment Variables Reference

​Verification

​Troubleshooting

​Next Steps

Quick Start

Architecture

Smart Contract

User Guides

​Getting Help

Build docs developers (and LLMs) love

System Requirements

Project Structure

Frontend Installation

Aleo Wallet Setup

Why Does Salud Require a Private Key?

Getting Your Private Key

Private Key Security Best Practices

Smart Contract Deployment (Optional)

Backend Setup (Optional - Deprecated)

Production Build

Environment Variables Reference

Verification

Troubleshooting

Next Steps

Getting Help