CommitLabs Frontend

The frontend application for the CommitLabs protocol, a decentralized platform for managing liquidity commitments on the Stellar network. Built with Next.js, TypeScript, and Tailwind CSS.

📋 Table of Contents

• Overview
• Documentation Index (docs/README.md)
• Features
• Architecture
• Getting Started
• Configuration
• Project Structure
• Backend API Changelog
• Settlement and Early Exit UI Flows
• Error Page Recovery Flows
• Contributing
• Community & Contributing
• API Reference
• License

🔭 Overview

CommitLabs allows users to create, manage, and trade liquidity commitments. These commitments are on-chain contracts that lock assets for a specified duration in exchange for yield, with specific compliance and risk parameters.

This frontend interacts with the CommitLabs Soroban smart contracts to:

1. Create new commitments with customizable parameters (Safe, Balanced, Aggressive).
2. Monitor the health and performance of existing commitments.
3. Trade commitments on a secondary marketplace.

✨ Features

• Commitment Creation Wizard: Step-by-step process to configure asset, amount, duration, and risk parameters.
• Dashboard: Real-time visualization of commitment health, including value history, drawdown, and compliance scores.
• Marketplace: Browse and filter active commitments available for purchase.
• Wallet Integration: Connect with Stellar wallets (e.g., Freighter) to sign transactions.
• Settlement and Early Exit Flows: Guided settlement eligibility, settlement success, and early-exit confirmation surfaces backed by preview and execution endpoints. See Settlement and Early Exit UI Flows.
• Error Page Recovery Flows: App Router error boundaries and recovery pages are documented in ERROR_PAGES_README.md.
• Responsive Design: Optimized for both desktop and mobile devices.

🏗 Architecture

The application is built using the Next.js App Router architecture.

• Framework: Next.js 14
• Language: TypeScript
• Styling: Tailwind CSS (v4) with CSS Modules for component-specific styles.
• State Management: React Context & Hooks (Local state for forms).
• Blockchain Interaction: @stellar/stellar-sdk and @stellar/freighter-api (via src/utils/soroban.ts).
• Data Visualization: recharts for health metrics and performance charts.

For a deep dive into the system design, modules, and data flow, please refer to ARCHITECTURE.md.

For a frontend-focused map of pages to components to API routes, plus wallet/auth state flow, see FRONTEND_ARCHITECTURE.md.

🧪 Testing

This project uses Vitest for unit and integration testing of API routes.

Running Tests

# Run all tests
pnpm test

# Run tests in watch mode (re-runs on file changes)
pnpm run test:watch

# Run tests with coverage report
pnpm run test:coverage

Coverage Requirements: The project enforces a 95% threshold on statements, branches, functions, and lines.

For detailed testing conventions, patterns, and best practices, see TESTING_GUIDE.md, which covers:

• Mocking fetch and external APIs
• Mocking the Freighter wallet API
• Using fake timers for async testing
• React Testing Library patterns and accessibility-first queries
• Test organization and naming conventions

🔄 Backend API Changelog

Breaking backend API changes are tracked in docs/backend-changelog.md. Update this changelog whenever a backend change can break existing frontend integrations.

🚀 Getting Started

Prerequisites

• Node.js 18.x or later
• pnpm (recommended) or npm/yarn
• A Stellar wallet extension (e.g., Freighter) installed in your browser.

Installation

1. Clone the repository:

   git clone https://github.com/your-org/commitlabs-frontend.git
   cd commitlabs-frontend

2. Install dependencies:

   pnpm install
   # or
   npm install

3. Set up environment variables: Copy the example environment file and configure it.

   cp .env.example .env

   See Configuration for details.

4. Run the development server:

   pnpm dev
   # or
   npm run dev

5. Open the application: Visit http://localhost:3000 in your browser.

⚙️ Configuration

The application requires the following environment variables (defined in .env):

Variable	Description	Default (Testnet)
NEXT_PUBLIC_SOROBAN_RPC_URL	URL of the Soroban RPC endpoint	https://soroban-testnet.stellar.org
NEXT_PUBLIC_NETWORK_PASSPHRASE	Stellar network passphrase	Test SDF Network ; September 2015
NEXT_PUBLIC_COMMITMENT_NFT_CONTRACT	Address of the Commitment NFT contract	Required
NEXT_PUBLIC_COMMITMENT_CORE_CONTRACT	Address of the Core Logic contract	Required
NEXT_PUBLIC_ATTESTATION_ENGINE_CONTRACT	Address of the Attestation Engine contract	Required

Note: The project also supports a versioned contract configuration via NEXT_PUBLIC_CONTRACTS_JSON and NEXT_PUBLIC_ACTIVE_CONTRACT_VERSION. See docs/config.md for details.

Browser-facing backend routes also use an explicit CORS policy helper. Configure trusted first-party origins with COMMITLABS_FIRST_PARTY_ORIGINS and public browser origins with COMMITLABS_PUBLIC_API_ORIGINS. See docs/backend-cors-policy.md for the route strategy and allowed methods. Backend API storage uses a provider-agnostic adapter. Configure COMMITLABS_STORAGE_PROVIDER=memory by default and see docs/backend-storage.md for adapter details.

📂 Project Structure

src/
├── app/                    # Next.js App Router pages and layouts
│   ├── commitments/        # Dashboard & Commitment Details
│   ├── create/             # Commitment Creation Wizard
│   ├── marketplace/        # Marketplace Listing
│   └── page.tsx            # Landing Page
├── components/             # Reusable UI components
│   ├── dashboard/          # Charts and metrics components
│   ├── modals/             # Global modals (Success, Errors)
│   └── ...
├── types/                  # TypeScript interfaces and types
├── hooks/                  # React hooks (useWallet, etc.)
├── lib/                    # Backend lib, services, mocks
├── utils/                  # Utility functions (Soroban, formatting)
└── ...

See [docs/FRONTEND_ARCHITECTURE.md](./docs/FRONTEND_ARCHITECTURE.md) for a
detailed page→component→API-route map and state/data-flow conventions.

🔒 Security Headers

This project includes a reusable helper to attach standard security headers to HTTP responses.

Usage:

1. Import the helper:

   import { attachSecurityHeaders } from "@/utils/response";

2. Wrap your response object before returning it in a route handler:

   import { NextResponse } from "next/server";
   import { attachSecurityHeaders } from "@/utils/response";
   
   export async function GET() {
     const response = NextResponse.json({ data: "secure content" });
     return attachSecurityHeaders(response);
   }

Customization:

• Content-Security-Policy (CSP): You can override the default CSP by passing a second argument.

  return attachSecurityHeaders(response, "default-src 'none'; img-src 'self'");

• Disabling/Modifying Headers: The attachSecurityHeaders function returns the modified Response object. You can further modify headers on the returned object if needed, or update the src/utils/response.ts file to change default behaviors globally.

📡 API Reference

A description of the backend endpoints exposed under /api can be found in:

• docs/backend-api-reference.md
• docs/backend-cors-policy.md
• docs/backend-storage.md

This document includes available routes, required parameters, and example requests/responses. It is intended for developers building against or testing the backend.

🤝 Contributing

We welcome contributions to CommitLabs! Before you start, please read our Developer Guide and check out the Documentation Index (docs/README.md) for details on all available documentation, coding standards, naming conventions, and testing guidelines.

To standardize submissions and streamline reviews, we use structured templates:

• Bug Reports: Use the Bug Report Form to report issues.
• Feature Requests: Use the Feature Request Form to suggest enhancements.
• Pull Requests: Every pull request must follow the checklist in our Pull Request Template (verifying 95% test coverage, the 96-hour campaign timeframe, lint checks, etc.).
• Discussions: Have questions or need support? Join our CommitLabs Discord server.

Steps to Contribute

1. Fork the repository and clone it to your local machine.
2. Create a branch for your changes:

   git checkout -b feat/your-feature-name

3. Develop & Test following the conventions in the Developer Guide. Ensure any new or modified logic meets the minimum 95% test coverage requirement.
4. Lint your code:

   pnpm lint

5. Commit and Push your changes to your fork.
6. Open a Pull Request pointing to the upstream repository's master branch.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Community & Contributing

We welcome contributions! Please review our community guidelines before getting started:

• Contributing Guidelines: Details on branching, PR flow, and test expectations.
• Code of Conduct: Our expectations for community interactions.
• Security Policy: How to report vulnerabilities privately.
• Developer Guide: Instructions on local setup, testing, and architecture.

Quick Start

1. Fork the repository and clone it to your local machine.
2. Create a new branch for your changes.
3. Make and test your updates following the project guidelines.
4. Commit and push your changes to your fork.
5. Open a Pull Request with a clear description.