Wallet Setup Guide - Salud Health

Overview

To use Salud Health, you need an Aleo wallet to secure your medical records and manage access. This guide covers everything from creating a new wallet to connecting existing wallets like Leo Wallet or Shield Wallet.

Why Salud Requires a Private Key

Understanding the Technical Difference

You might wonder why you can’t just click “Connect Wallet” like on other dApps. Here’s why Salud is different:

Standard dApp (Browser Wallet Connection)

How it works:

Browser Wallet → Signs transaction → Blockchain
     ↑
 (Easy connection)

What it does:

Wallet extension signs transactions
Data sent to blockchain in standard format
Suitable for DeFi, NFTs, and public transactions

Salud Health (Private Key Encryption)

How it works:

Your Data → Encrypt with Private Key → Backend → Blockchain
                ↑
         (Needs private key for encryption)

What it does:

Encrypts medical data before leaving your browser
Generates cryptographic proofs for zero-knowledge verification
Creates encrypted access tokens for sharing
Maintains server-side session for blockchain interaction

Why Browser Wallets Don’t Work

Technical LimitationsBrowser wallets (Leo, Shield, Puzzle) don’t expose the private key needed for:

Client-side data encryption of medical records
Cryptographic proof generation for access control
View key derivation for record sharing
Server-side session management with the Aleo blockchain

The Privacy Benefit

This design actually provides stronger security for medical data:

Feature	Regular dApp	Salud Health
Connection	Click “Connect”	Paste private key
Data Encryption	❌ Not encrypted	✅ Encrypted with your key
Medical Data Privacy	❌ Visible to dApp	✅ Only you can decrypt
Server Can Read Data	❌ Yes	✅ No (zero-knowledge)
Sharing with Doctors	❌ Not possible	✅ Time-limited access tokens
Security Level	Standard	HIPAA-grade encryption

Bottom LineSalud requires a private key because it provides medical-grade privacy that browser wallets can’t offer. Your health data deserves the highest level of protection!

Getting an Aleo Private Key

You have four options for obtaining an Aleo private key:

Option 1: Export from Leo Wallet (Recommended)

If you already have Leo Wallet installed:

Open Leo Wallet

Click the Leo Wallet browser extension icon in your browser toolbar.

Navigate to Settings

Click on your account name or avatar, then go to Settings → Security & Privacy.

Export Private Key

Click “Export Private Key” and enter your wallet password to authenticate.

Copy the Key

Your private key will be displayed (starts with APrivateKey1...). Copy it to your clipboard.

This key provides full access to your wallet. Never share it with anyone.

Paste into Salud

Return to Salud Health and paste the private key into the wallet connect screen.

Option 2: Export from Shield Wallet

If you use Shield Wallet:

Open Shield Wallet

Launch the Shield Wallet browser extension.

Access Account Settings

Navigate to Account Settings from the main menu.

Export Private Key

Select “Export Private Key” and authenticate with your password.

Copy and Use

Copy the displayed private key (starts with APrivateKey1...) and paste it into Salud Health.

Option 3: Generate New Account (Testing)

Don’t have a wallet yet? Generate a new account directly in Salud:

Navigate to Salud Health

Open the Salud Health application in your browser.

Click 'Generate New'

On the wallet connect screen, click the “Generate New” button.

Save Your Private Key

A new Aleo account will be generated with a private key. Save this key securely - you’ll need it to access your account later.

If you lose this private key, you lose access to all your medical records permanently. There is no recovery mechanism.

Import to Wallet (Optional)

You can later import this private key into Leo Wallet or Shield Wallet for easier management.

Option 4: Use Existing Aleo Account

If you already have an Aleo account from:

Aleo SDK development
Other Aleo dApps
Previous Salud sessions
Command-line wallet generation

Simply use your existing private key (must start with APrivateKey1...).

Understanding Your Wallet

Private Key Format

Aleo private keys have a specific format:

APrivateKey1zkp...[53 more characters]...xyz

Characteristics:

Starts with APrivateKey1
Total length: 59 characters
Contains alphanumeric characters
Case-sensitive

If your key doesn’t match this format, it’s not a valid Aleo private key.

What Your Private Key Controls

🔐 Wallet Ownership

Your private key proves ownership of your Aleo wallet address. It’s like the password to your bank account.

📝 Transaction Signing

When creating records or granting access, your private key signs transactions to authorize them on the Aleo blockchain.

🔒 Data Encryption/Decryption

Your private key encrypts medical data before storage and decrypts it when you view records. This is critical for privacy!

🎫 Access Token Generation

When sharing records with doctors, your private key generates cryptographic access tokens that prove viewing rights.

Deriving Your Wallet Address

Your public wallet address is derived from your private key:

Private Key: APrivateKey1zkp...
       ↓
Public Address: aleo1abc...xyz (63 characters)

Patients and doctors will see your wallet address (not your private key) when sharing records.

Connecting to Salud Health

First-Time Connection

Navigate to Salud Health

Open http://localhost:5173 (or your deployed Salud Health URL) in your browser.

Enter Private Key

On the wallet connect screen, paste your Aleo private key into the input field.

Click Connect

Click the “Connect” button to establish your session.

Wait for Verification

Salud Health will:

Verify your private key format
Derive your wallet address
Create a server-side session
Fetch your existing records from the Aleo blockchain

Access Dashboard

Once connected, you’ll be redirected to your dashboard with all your medical records.

Reconnecting

Each time you visit Salud Health, you’ll need to reconnect:

Your session expires when you close the browser or after a timeout period
No credentials are stored locally for security reasons
Simply paste your private key again to reconnect

Why No Persistent Login?For maximum security, Salud doesn’t store your private key. While this means reconnecting each visit, it ensures your key can’t be compromised through the application.

Security Best Practices

Storing Your Private Key

Never share your private key with anyone! It provides complete access to your wallet and medical records.

Recommended storage methods:

Password Manager (Recommended)

Store your private key in a reputable password manager like:

1Password
Bitwarden
LastPass
Dashlane

Use a strong master password and enable 2FA on your password manager.

Hardware Wallet

For production use with sensitive medical data, consider storing your Aleo private key on a hardware wallet like:

Ledger
Trezor

Note: You’ll still need to export the key to use Salud, but the hardware wallet provides secure storage.

Encrypted File

Save your private key in an encrypted file:

Use built-in OS encryption (FileVault on macOS, BitLocker on Windows)
Store in an encrypted container (VeraCrypt)
Keep backups in separate secure locations

Paper Backup

Write your private key on paper and store it in a secure location:

Safe deposit box
Home safe
Fireproof document storage

Use multiple copies in different locations for redundancy.

Avoid these methods: ❌ Plain text files on your computer ❌ Email (even drafts) ❌ Cloud storage without encryption ❌ Screenshots or photos ❌ Unencrypted notes apps ❌ Shared documents or messaging apps

Using Salud Securely

Use HTTPS

Always access Salud Health over HTTPS to prevent man-in-the-middle attacks.

Verify URL

Check that you’re on the legitimate Salud Health domain before entering your private key.

Use Private Browsing (Optional)

Consider using incognito/private mode when accessing sensitive medical records to prevent browser history storage.

Lock Your Device

Always lock your computer/phone when stepping away during an active Salud session.

Use Dedicated Wallet (Recommended)

For maximum privacy, create a separate Aleo wallet specifically for Salud Health rather than reusing wallets from other dApps.

Network Security

Public WiFi RiskAvoid entering your private key on public WiFi networks. Use:

Cellular data connection
VPN on trusted network
Home/office secure WiFi

Session Management

Session Timeout: Your Salud session expires after inactivity
Manual Disconnect: No explicit disconnect button - sessions are memory-only
Browser Closure: Closing the browser immediately ends your session
Private Key Handling: Your key is only kept in browser memory during active sessions

Using Your Existing Wallet

Can I Use My Leo/Shield Wallet Balance?

Yes! The private key you export from Leo Wallet or Shield Wallet is the same key that controls your wallet. This means:

✅ Same Aleo wallet address
✅ Same token balance
✅ Same transaction history
✅ Access to the same on-chain records

You’re not creating a new wallet - you’re using your existing wallet’s private key in Salud’s interface.

Managing Multiple Applications

Think of it like this:

Leo Wallet = A secure vault for your private key that lets you sign transactions
Salud Health = A specialized medical app that needs your private key for encryption
Your Wallet = The underlying Aleo account controlled by the same private key

It’s like using the same bank account on different banking apps.

Switching Between Wallets

You can use different Aleo wallets in Salud:

Personal Records Wallet: For your own medical records
Professional Wallet: If you’re a doctor accessing patient records
Family Member Wallets: Managing records for dependents

Simply paste a different private key to switch accounts.

Troubleshooting

'Invalid private key' error

Possible causes:

Private key doesn’t start with APrivateKey1
Key is not exactly 59 characters
Extra spaces or line breaks were copied
Wrong format (not an Aleo private key)

Solutions:

Re-export from your wallet carefully
Check for hidden characters or spaces
Verify the key starts with APrivateKey1
Try generating a new key if unsure

Cannot connect to backend

Possible causes:

Backend server not running (if self-hosting)
Firewall blocking connection
Incorrect API URL configuration

Solutions:

Ensure backend is running on port 3001
Check VITE_API_URL in frontend .env
Verify firewall settings
Check browser console for connection errors

Private key not recognized after copy-paste

Possible causes:

Clipboard added extra characters
Key was split across multiple lines
Copy-paste encoding issue

Solutions:

Type the key manually
Use a text editor to clean up formatting
Copy from wallet extension again
Check for invisible Unicode characters

Lost private key - can I recover my records?

Unfortunately, no.Aleo blockchain uses cryptographic encryption where your private key is the only way to decrypt your records. There is no password reset or recovery mechanism.Prevention:

Store multiple encrypted backups
Use a password manager
Write down paper backups
Test recovery process periodically

Different wallet address than expected

Possible causes:

Using a different private key than intended
Multiple accounts in your wallet extension
Exported key from wrong account

Solutions:

Verify which account is active in Leo/Shield Wallet
Check that the exported key matches the expected address
Derive the public address from your private key to confirm

Advanced Topics

Demo Mode (Testing)

For testing without spending Aleo credits:

Configure backend .env:
```
DEMO_MODE=true
```
In demo mode:
- ✅ All features work normally
- ✅ Records stored in localStorage
- ✅ No real blockchain transactions
- ⚠️ Records won’t persist across browsers/devices

Testnet vs Mainnet

Salud Health currently uses Aleo Testnet:

Free to use (test credits)
Perfect for development and testing
Records are real but use testnet tokens
No real value at stake

Switching to Mainnet (when available): Update ALEO_API_URL in backend .env:

ALEO_API_URL=https://api.explorer.provable.com/v1/mainnet

Mainnet transactions cost real Aleo credits. Ensure you have sufficient balance before creating records.

Checking Your Balance

To check your Aleo wallet balance:

Via Salud: Dashboard displays your balance after connection
Via Leo Wallet: Check balance in the wallet extension
Via Aleo Explorer: Visit https://explorer.aleo.org and search your address
Via API: GET /api/wallet/balance/:sessionId endpoint

Importing Generated Keys to Leo Wallet

If you generated a new account in Salud and want to manage it via Leo Wallet:

Open Leo Wallet

Launch the Leo Wallet browser extension.

Select 'Import Account'

Click the account menu and choose “Import Account”.

Enter Private Key

Paste the private key generated by Salud.

Set Account Name

Give your account a name (e.g., “Salud Health Records”).

Confirm Import

Complete the import process. Your Salud-generated account is now managed by Leo Wallet.

Next Steps

Now that your wallet is set up:

Patient Guide

Learn how to create and manage your medical records

Doctor Guide

Understand how to access shared patient records

Security Checklist

Before using Salud Health, ensure:

Private key is securely stored (password manager or hardware wallet)
Multiple backups exist in separate secure locations
Using HTTPS connection to Salud Health
Verified the application URL is legitimate
Understand that sessions are temporary and require reconnection
Know that lost private keys cannot be recovered
Using a secure network (not public WiFi)
Device is protected with strong password/biometrics
Antivirus/security software is active and updated

Get Started

Core Features

User Guides

Architecture

​Overview

​Why Salud Requires a Private Key

​Understanding the Technical Difference

​Why Browser Wallets Don’t Work

​The Privacy Benefit

​Getting an Aleo Private Key

​Option 1: Export from Leo Wallet (Recommended)

​Option 2: Export from Shield Wallet

​Option 3: Generate New Account (Testing)

​Option 4: Use Existing Aleo Account

​Understanding Your Wallet

​Private Key Format

​What Your Private Key Controls

​Deriving Your Wallet Address

​Connecting to Salud Health

​First-Time Connection

​Reconnecting

​Security Best Practices

​Storing Your Private Key

​Using Salud Securely

​Network Security

​Session Management

​Using Your Existing Wallet

​Can I Use My Leo/Shield Wallet Balance?

​Managing Multiple Applications

​Switching Between Wallets

​Troubleshooting

​Advanced Topics

​Demo Mode (Testing)

​Testnet vs Mainnet

​Checking Your Balance

​Importing Generated Keys to Leo Wallet

​Next Steps

Patient Guide

Doctor Guide

​Security Checklist

Build docs developers (and LLMs) love

Overview

Why Salud Requires a Private Key

Understanding the Technical Difference

Why Browser Wallets Don’t Work

The Privacy Benefit

Getting an Aleo Private Key

Option 1: Export from Leo Wallet (Recommended)

Option 2: Export from Shield Wallet

Option 3: Generate New Account (Testing)

Option 4: Use Existing Aleo Account

Understanding Your Wallet

Private Key Format

What Your Private Key Controls

Deriving Your Wallet Address

Connecting to Salud Health

First-Time Connection

Reconnecting

Security Best Practices

Storing Your Private Key

Using Salud Securely

Network Security

Session Management

Using Your Existing Wallet

Can I Use My Leo/Shield Wallet Balance?

Managing Multiple Applications

Switching Between Wallets

Troubleshooting

Advanced Topics

Demo Mode (Testing)

Testnet vs Mainnet

Checking Your Balance

Importing Generated Keys to Leo Wallet

Next Steps

Security Checklist