VacciChain Backend API

Express.js backend for VacciChain, a blockchain-based vaccination record platform on Stellar Network using Soroban smart contracts.

Features

• SEP-10 Web Authentication: Challenge-response based authentication with Stellar keypairs
• JWT Token Generation: Role-based access control (issuer vs patient)
• Soroban Integration: Direct smart contract interaction for vaccination NFT minting and verification
• RESTful API: Clean, documented endpoints for vaccination operations

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    VacciChain Backend                        │
├─────────────────────────────────────────────────────────────┤
│ Express.js Application                                      │
│  ├── SEP-10 Auth Middleware (Challenge/Response)            │
│  ├── JWT Authentication Middleware                          │
│  ├── Issuer Role Verification (Soroban Read)                │
│  └── API Routes                                             │
├─────────────────────────────────────────────────────────────┤
│ Stellar Integration                                         │
│  ├── Soroban RPC Client (Contract Reads & Writes)           │
│  ├── TransactionBuilder (Envelope Construction)             │
│  └── Keypair Management (SEP-10 Signing)                    │
└─────────────────────────────────────────────────────────────┘

API Endpoints

Authentication

1. Get SEP-10 Challenge

POST /v1/auth/sep10
Content-Type: application/json

{
  "publicKey": "GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Response:
{
  "success": true,
  "challengeXdr": "AAAAAgAAAAB...",
  "nonce": "a1b2c3d4e5f6g7h8"
}

2. Verify Challenge & Get JWT

POST /v1/auth/verify
Content-Type: application/json

{
  "signedXdr": "AAAAAgAAAAB...",
  "publicKey": "GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Response:
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "role": "issuer|patient",
  "publicKey": "GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Vaccination Operations

3. Issue Vaccination Record (Protected)

POST /v1/vaccination/issue
Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

{
  "patientAddress": "GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "vaccineName": "COVID-19 Pfizer",
  "dateAdministered": "2024-01-15T10:30:00Z"
}

Response:
{
  "success": true,
  "txHash": "0x1234567890abcdef...",
  "message": "Vaccination record minting transaction submitted successfully."
}

4. Verify Vaccination Status (Public)

GET /v1/verify/:wallet

Response:
{
  "success": true,
  "walletAddress": "GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "isVerified": true,
  "recordCount": 3,
  "verifiedAt": "2024-07-10T12:30:00.000Z"
}

Installation

Prerequisites

• Node.js 18+ and npm
• Stellar Testnet keypair (for testing)
• Soroban contract ID

Setup

1. Clone the repository:

git clone https://github.com/Vacci-chain/vacchain-backend.git
cd vacchain-backend

2. Install dependencies:

npm install

3. Configure environment:

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

4. Start the server:

npm start
# Or for development with auto-reload:
npm run dev

The server will listen on http://localhost:4000 by default.

Environment Variables

Variable	Description	Example
PORT	Server port	4000
JWT_SECRET	Secret for JWT signing	your-secret-key
STELLAR_NETWORK	Network selection	TESTNET or MAINNET
HORIZON_URL	Horizon API endpoint	https://horizon-testnet.stellar.org
SOROBAN_RPC_URL	Soroban RPC endpoint	https://soroban-testnet.stellar.org
VACCINATIONS_CONTRACT_ID	Soroban contract ID	CDW...
SEP10_SERVER_KEY	Server secret key for SEP-10	SA...

Security Considerations

• SEP-10 Replay Protection: Nonces are stored and validated to prevent replay attacks
• JWT Expiration: Tokens expire after 1 hour
• Issuer Authorization: Verified on-chain before allowing mint operations
• CORS: Configured for specified origins
• Environment Variables: Sensitive data stored in .env (not in repository)

Testing

Run tests with:

npm test

Development

Restart on file changes:

npm run dev

Lint code:

npm run lint

Contract Integration

The backend interacts with a Soroban smart contract exposing:

pub fn mint_vaccination(
    patient: Address,
    vaccine_name: String,
    date_administered: u64,
    issuer: Address
) -> Result<(), Error>

pub fn verify_vaccination(patient: Address) -> Result<Vec<VaccinationRecord>, Error>

pub fn is_authorized_issuer(issuer: Address) -> bool

Deployment

Docker

docker build -t vaccichain-backend .
docker run -p 4000:4000 --env-file .env vaccichain-backend

Production Checklist

• Set strong JWT_SECRET in environment
• Configure SEP10_SERVER_KEY with mainnet keypair
• Use STELLAR_NETWORK=MAINNET with mainnet RPC endpoints
• Enable HTTPS
• Set up proper logging and monitoring
• Configure database for challenge storage (instead of in-memory)
• Set up rate limiting for production

License

MIT

Support

For issues, questions, or contributions, please visit: https://github.com/Vacci-chain/vacchain-backend

Authors

VacciChain Team