Halo
Sign InGet Started

Documentation

Everything you need to build with Halo Protocol. From connecting a wallet and joining your first circle to deploying contracts and integrating the SDK.

Getting Started

Set up your development environment and deploy your first lending circle in minutes. Covers wallet connection, identity registration, and circle creation.

Smart Contracts

Deep dive into the 8 Clarity smart contracts powering Halo Protocol: identity, credit scoring, vaults, circles, sBTC staking, and SIP-010 token standards.

API Reference

Complete REST API documentation covering 15 endpoints: authentication, identity management, circle operations, credit scoring, faucet, and admin sync.

SDK & Developer Tools

Integrate Halo Protocol into your application with @stacks/connect for wallets and @stacks/transactions for contract interactions. Includes code examples.

Deployment Guide

Deploy Halo Protocol to Stacks testnet or mainnet. Covers contract deployment order, configuration, verification, and CI/CD pipeline setup.

Architecture

Understand the full-stack architecture: Clarity contracts on Stacks L2, Next.js 14 backend with Prisma, and a React frontend with wallet integration.

Getting Started

1. Prerequisites

Before building with Halo Protocol, ensure you have the following installed:

# Node.js 18+ and npm

node --version

# Clarinet v3.13+ for contract development

clarinet --version

# A Stacks wallet (Leather or Xverse)

2. Clone and Install

git clone https://github.com/halo-protocol/halo-stacks.git

cd halo-stacks

npm install

3. Run Contract Tests

Verify all 232 contract tests pass with Vitest and the Clarinet SDK:

npx vitest run

4. Start the Application

Launch the full-stack Next.js application with the backend API and frontend:

# Copy environment template

cp .env.example .env

# Run database migrations

npx prisma migrate dev

# Start dev server

npm run dev

Smart Contracts

Halo Protocol consists of 8 Clarity smart contracts deployed on the Stacks blockchain. Contracts must be deployed in the following order due to inter-contract dependencies.

1

halo-sip010-trait

SIP-010 fungible token trait definition

2

halo-identity

On-chain identity registration and DID management

3

halo-mock-token

Mock hUSD token for testnet (SIP-010 compliant)

4

halo-mock-sbtc

Mock sBTC token for testnet staking

5

halo-credit

Decentralized credit scoring (300-850 range)

6

halo-vault

Secure token vault for circle contributions

7

halo-sbtc-staking

sBTC staking for yield and credit boost

8

halo-circle

ROSCA lending circle lifecycle management

Architecture

Smart Contracts

8 Clarity contracts on Stacks L2, secured by Bitcoin. Handles identity, credit scoring, token vaults, lending circles, and sBTC staking. Written in Clarity 3 (Epoch 3.0).

Backend API

Next.js 14 App Router with 15 API routes. Prisma v6 ORM with PostgreSQL (Supabase). NextAuth.js v4 for OAuth. On-chain sync keeps the database in lockstep with contract state.

Frontend

React with Tailwind CSS v3 and shadcn/ui components. @stacks/connect v8 for Leather and Xverse wallet integration. Same-origin architecture eliminates CORS complexity.

Deployment

Testnet Deployment

Deploy all 8 contracts to Stacks testnet with the deployment script. The script handles ordering, authorization calls, and verification automatically.

# Dry run (no transactions broadcast)

npx ts-node scripts/deploy-testnet.ts --dry-run

# Execute deployment

npx ts-node scripts/deploy-testnet.ts --execute

# Verify deployment

npx ts-node scripts/verify-deployment.ts

CI/CD Pipeline

GitHub Actions runs 4 parallel jobs on every push: contract tests, backend API tests, frontend tests, and a full production build. All 412 tests must pass before merging to main.