Getting Started

Install ZibaXeer locally and run the full development stack

Getting Started

This guide walks you through cloning the repo, installing dependencies, configuring your environment, and running all three services locally.

---

Prerequisites

Tool	Minimum Version	Install
Node.js	>= 20.0.0	nodejs.org
pnpm	>= 8.0.0	npm i -g pnpm
Foundry	latest	getfoundry.sh
PostgreSQL	>= 15	postgresql.org
Redis	>= 7	redis.io
Git	any	git-scm.com

---

Installation

1. Clone the repository

   git clone https://github.com/thetruesammyjay/ZibaXeer.git
   cd ZibaXeer
   
2. Install all workspace dependencies

   pnpm install
   

   This installs dependencies for all packages: apps/backend, apps/frontend, apps/indexer, and all packages/*.

---

Environment Variables

Root .env

Create a .env file at the project root:

# ─── Network ──────────────────────────────────────────────
HYPERPAXEER_RPC_URL=https://public-mainnet.rpcpaxeer.online/evm
CHAIN_ID=125

# ─── Deployer ──────────────────────────────────────────────
DEPLOYER_PRIVATE_KEY=0x...
DEPLOYER_ADDRESS=0x...

# ─── Argus Oracle ──────────────────────────────────────────
ARGUS_ORACLE_ENDPOINT=https://api.hyperpaxeer.com/argus/v1
ARGUS_API_KEY=your_api_key_here

Backend

Create apps/backend/.env:

# ─── Database ──────────────────────────────────────────────
DATABASE_URL=postgresql://postgres:password@localhost:5432/zibaxeer

# ─── Redis ─────────────────────────────────────────────────
REDIS_URL=redis://127.0.0.1:6379

# ─── Server ────────────────────────────────────────────────
PORT=4000

Indexer

Create apps/indexer/.env:

# ─── Network ──────────────────────────────────────────────
RPC_URL=https://public-mainnet.rpcpaxeer.online/evm

# ─── Contracts ─────────────────────────────────────────────
VAULT_FACTORY_ADDRESS=0x...
KNOWN_VAULT_ADDRESSES=0xVault1,0xVault2   # comma-separated, optional

# ─── Redis ─────────────────────────────────────────────────
REDIS_URL=redis://127.0.0.1:6379

Frontend

Create apps/frontend/.env.local:

NEXT_PUBLIC_RPC_URL=https://public-mainnet.rpcpaxeer.online/evm
NEXT_PUBLIC_CHAIN_ID=125
NEXT_PUBLIC_EXPLORER_URL=https://paxscan.paxeer.app
NEXT_PUBLIC_API_URL=http://localhost:4000

---

Database Setup

1. Create the database

   createdb zibaxeer
   
2. Generate the Prisma client

   cd packages/db
   pnpm prisma generate
   
3. Run migrations

   pnpm prisma migrate dev --name init
   

---

Running Locally

Open three separate terminals:

1. Terminal 1 — Backend API

   cd apps/backend
   pnpm dev
   

   Server starts at http://localhost:4000. Verify with:

   curl http://localhost:4000/health
   # → {"status":"ok","service":"Zibaxeer API Server"}
   
2. Terminal 2 — Indexer

   cd apps/indexer
   pnpm dev
   

   The indexer connects to HyperPaxeer RPC, begins watching the VaultFactory for VaultDeployed events, and listens to any vaults listed in KNOWN_VAULT_ADDRESSES.

3. Terminal 3 — Frontend

   cd apps/frontend
   pnpm dev
   

   Dashboard available at http://localhost:3000.

---

Smart Contract Development

Compile contracts

cd contracts
forge build

Run tests

# Unit tests
forge test

# With verbosity
forge test -vvv

# Fuzz tests (10,000 runs)
forge test --fuzz-runs 10000

# Coverage
forge coverage --report lcov

Local fork

# Fork HyperPaxeer mainnet locally on port 8545
anvil --fork-url https://public-mainnet.rpcpaxeer.online/evm --chain-id 125

---

Workspace Scripts

From the monorepo root you can run scripts across all packages:

pnpm --filter @zibaxeer/backend dev
pnpm --filter @zibaxeer/frontend dev
pnpm --filter @zibaxeer/indexer dev

---

Troubleshooting

`pnpm install` fails on a package

Make sure you’re on Node.js >= 20 and pnpm >= 8:

node --version
pnpm --version

Prisma client not found

Regenerate the client after any schema change:

cd packages/db
pnpm prisma generate

Redis connection refused

Ensure Redis is running:

# macOS / Linux
redis-server

# Windows (via WSL or Docker)
docker run -p 6379:6379 redis:7-alpine

Indexer not picking up events

• Confirm VAULT_FACTORY_ADDRESS in apps/indexer/.env matches the deployed contract
• Check the RPC endpoint is reachable
• Verify REDIS_URL matches the backend’s REDIS_URL (same Redis instance)