How blazarlabs-io/blazar-hydra works
Project type and purpose
• Type: A Node.js/TypeScript-based backend service that exposes an HTTP API for managing Cardano/Hydra payment channels (“heads”)
• Purpose: Receive API calls (open head, deposit, pay, withdraw, close head), orchestrate off-chain transaction construction/submission, persist state, and deploy/validate on-chain smart contracts written in Aiken
File structure
• src/api – HTTP entry-points (server.ts, routes.ts), request validation (zod schemas), middleware (request-ID injection)
• src/offchain – Handlers (business workflows), tx-builders (Cardano transactions), utility libs (type definitions, Hydra helpers), a simple demo test
• src/onchain/hydra-pay – Aiken smart contract code and workflows (validators, types, utils) with CI
• src/prisma – Prisma ORM setup and embedded SQLite dev DB
• src/shared – Shared TypeScript types and Prisma schema definitions
• config.ts + logger/ – Global config and Pino logger abstraction
Main components and interactions
a. API Server
– Exposes REST endpoints via entry-points/routes.ts
– Validates with zod schemas and adds request IDs via middleware
– Injects config and logger
b. Off-chain Engine
– Handlers receive calls from API layer
– Use tx-builders to construct Cardano transactions (deposit, pay, merge funds, withdraw)
– Use Hydra library (hydra.ts) to manage head protocol messages
– Submit transactions to a Cardano node (RPC endpoint)
– Persist head state and transaction metadata via Prisma ORM
c. On-chain Validators
– Aiken language contracts in src/onchain/hydra-pay/validators
– Deployed via CLI or CI workflow
– Validate UTXOs according to Hydra-Pay logic
d. Database (Prisma)
– Schema stores user balances, head session info, tx history
– Generates a SQLite dev DB / can swap to Postgres in prod
e. External Services
– Cardano node / network (for submitting and confirming txs)
– Hydra network peers (for head messaging)
Architectural patterns and design principles
• Separation of concerns: Clear layers—API entrypoints, application logic (handlers), domain/Tx-builder libs, infrastructure (DB, network)
• Hexagonal/Ports & Adapters style: API and on-chain are adapters; off-chain lib is the core
• Schema-driven validation: zod for runtime type safety
• Sidecar DI: config.ts and logger definitions injected into modules
• Stateless handlers: Each handler builds a fresh tx, submits it, updates DB