VaultLink

A decentralized invoice financing protocol built on Stellar Soroban.

Overview

VaultLink enables businesses to tokenize invoices as NFTs on Stellar and obtain immediate financing from investors. The protocol consists of:

• Backend: NestJS API with JWT authentication and Stellar wallet signature verification
• Smart Contracts: Soroban Rust contracts for invoice NFTs and financing pools
• Database: PostgreSQL with TypeORM for data persistence
• Cache: Redis for session management and caching

Architecture & Services

The protocol is designed as a monorepo, leveraging Docker to orchestrate its core infrastructure dependencies.

Project Structure

.
├── vaultlink/
│   ├── apps/
│   │   ├── backend/       # NestJS API server
│   │   └── contracts/     # Soroban Rust Workspace (Registry & Core)
│   └── docs/              # Documentation
└── docker-compose.yml      # Infrastructure Orchestration (PostgreSQL & Redis)

Services (Dockerized)

The following services are automatically provisioned via the docker-compose.yml file:

• PostgreSQL 16: Primary relational database for user and invoice data.
• Redis 7: High-performance cache for session management and rate limiting.

Prerequisites

• Node.js 18+
• Rust 1.70+ (for Soroban contracts)
• Docker & Docker Compose
• PostgreSQL 16+ (via Docker)
• Redis 7+ (via Docker)

Quick Start

1. Environment Configuration

The backend application expects its environment variables in the apps/backend/ directory.

cd vaultlink
cp .env.example apps/backend/.env

Ensure your apps/backend/.env contains the correct connection strings for your local environment (e.g., using localhost:5432 for the database if running the app on your host machine).

2. Start Infrastructure (Docker)

Crucial: VaultLink relies on Docker Compose to spin up the required database and cache layers. From the project root, run:

docker-compose up -d

Verify that both services are healthy:

docker ps

3. Start the Backend API

Navigate to the backend directory, install dependencies, and start the development server:

cd apps/backend
npm install
npm run start:dev

The server will start at http://localhost:3000.

4. Interactive API Documentation

Once the application is running, you can explore and test the API endpoints (Registration, Login, Invoice creation, etc.) via the Swagger UI

4. Build and Deploy Contracts

cd apps/contracts
cargo build --release
# Deploy to Stellar testnet
stellar contract deploy --wasm target/wasm32-unknown-unknown/release/vaultlink_core.wasm

API Endpoints

Authentication

• POST /auth/connect-wallet - Connect Stellar wallet
• POST /auth/verify-signature - Verify wallet signature
• POST /auth/refresh - Refresh JWT token

Invoices

• GET /invoices - List all invoices
• POST /invoices - Create new invoice
• GET /invoices/:id - Get invoice details
• PUT /invoices/:id - Update invoice
• DELETE /invoices/:id - Delete invoice

Financing

• GET /financing/offers - List financing offers
• POST /financing/offers - Create financing offer
• POST /financing/offers/:id/accept - Accept financing offer

Environment Variables

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	-
REDIS_HOST	Redis server host	localhost
REDIS_PORT	Redis server port	6379
JWT_SECRET	Secret for JWT signing	-
STELLAR_NETWORK	Stellar network to connect to (testnet or public)	testnet
STELLAR_RPC_URL	Stellar Soroban RPC URL	https://soroban-testnet.stellar.org
STELLAR_HORIZON_URL	Stellar Horizon RPC URL	https://horizon-testnet.stellar.org
INVOICE_REGISTRY_CONTRACT_ID	Deployed Soroban Invoice Registry Contract ID	-

Running Tests

# Backend tests
cd apps/backend
npm run test

# Contract tests (Rust)
cd apps/contracts
cargo test

Project Structure

Backend (apps/backend)

src/
├── auth/           # JWT + Stellar wallet auth
├── invoice/        # Invoice management
├── financing/      # Financing offers
├── transaction/    # Blockchain transactions
├── user/           # User profiles
└── common/         # Shared utilities

Contracts (apps/contracts)

vaultlink-core/
├── src/
│   ├── invoice.rs   # Invoice NFT contract
│   ├── financing.rs # Financing pool contract
│   ├── storage.rs   # Contract storage
│   └── lib.rs       # Contract entry point
└── Cargo.toml

License

MIT