The off-chain metadata, query, and indexing API service for the Volt task escrow protocol on the Stellar network. Built using Fastify, Prisma, PostgreSQL, and Zod, this service facilitates fast task indexing, rich metadata queries, and acts as the bridging database layer for client interfaces.

• Rich Metadata Store: Maintains off-chain task documentation (titles, descriptions, resources) while keeping final settlements secured on-chain.
• Advanced Query Endpoints: Offloads complex filtering, pagination, and indexing queries from the Soroban ledger to a fast PostgreSQL database.
• Strict Data Validation: Utilizes Zod schemas to ensure all request bodies, query parameters, and database schemas strictly validate Stellar addresses, contract hashes, and data types.
• Docker-Ready: Packaged with a preconfigured Docker Compose setup for local development.

• Framework: Fastify (TypeScript)
• Database: PostgreSQL
• ORM: Prisma
• Validation: Zod
• Logger: Pino & Pino-Pretty
• Testing: Vitest

• Node.js (v20+)
• Docker & Docker Compose

Copy the example environment configuration file and modify the database credentials and application settings as needed:

cp .env.example .env

Start the PostgreSQL container, generate the Prisma client, apply database migrations, and launch the Fastify server:

# Start PostgreSQL container in the background
docker-compose up -d

# Generate Prisma Client classes
npm run db:generate

# Apply migrations to database
npm run db:migrate

# Launch Fastify development server with hot-reload
npm run dev

To build and run the compiled Javascript bundle:

# Build the TypeScript codebase
npm run build

# Start the application in production mode
npm run start

GET /health Returns the status and health details of the backend service and database connection.

POST /v1/tasks Creates off-chain task metadata linked to a Stellar contract and transaction.

• Payload Schema: Matches the Zod schema for task creation parameters.

GET /v1/tasks Retrieves a paginated list of tasks.

• Query Parameters:
  • page: Page index (default: 1)
  • limit: Tasks per page (default: 20)
  • status: Filter by task status (e.g., CREATED, FUNDED, ASSIGNED, SUBMITTED, COMPLETED, CANCELLED)

GET /v1/tasks/:id Retrieves the detailed record of a task using its unique database ID.

GET /v1/tasks/onchain/:chainId/:contractAddress/:taskId Retrieves task metadata mapped to Stellar ledger identifiers.

• chainId: Network identifier/passphrase.
• contractAddress: Stellar contract ID.
• taskId: The unique task ID generated by the smart contract.

PATCH /v1/tasks/:id/status Updates the status of a task in the off-chain database.

Manage the schema and explore the database records using Prisma CLI scripts:

# Run database schema migrations
npm run db:migrate

# Generate Prisma Client models
npm run db:generate

# Open the Prisma Studio GUI to view database contents
npm run db:studio

Verify code standards and check system reliability:

# Run tests with Vitest
npm run test

# Run tests once (e.g., in CI environments)
npm run test:run

# Lint codebase
npm run lint

# Format codebase
npm run format

# Verify format
npm run format:check

# Typecheck TypeScript files
npm run typecheck

This API service is currently in MVP stage. Authentication, rate limiting, and access authorization are not pre-configured. It is designed only for internal sandbox or testnet usage. Always deploy behind a secure API gateway or reverse proxy in production environments.

This project is licensed under the MIT License.