Developers Overview

Welcome to the KhipuVault developer documentation. Build decentralized Bitcoin savings applications on the Mezo blockchain using our comprehensive APIs, smart contracts, and integration tools.

What You Can Build

Quick Links

Technology Stack

KhipuVault is a modern full-stack monorepo built with:

Frontend

• Next.js 15 - React framework with App Router
• Wagmi 2.x - React hooks for Ethereum
• Viem 2.x - TypeScript Ethereum library
• React Query 5 - Server state management
• Tailwind CSS - Styling framework

Backend

• Express.js - REST API server
• Prisma - Database ORM (PostgreSQL)
• SIWE - Sign-In With Ethereum authentication
• Pino - Structured logging

Smart Contracts

• Solidity 0.8.26 - Smart contract language
• Foundry - Development framework (Forge, Cast, Anvil)
• OpenZeppelin - Security libraries
• Mezo Blockchain - Bitcoin-backed L2

Blockchain

• ethers.js 6.x - Event indexing
• PostgreSQL - Indexed event storage

Network Details

Mezo Testnet

{
  chainId: 31611,
  rpcUrl: "https://rpc.test.mezo.org",
  blockExplorer: "https://explorer.test.mezo.org",
  nativeCurrency: {
    name: "Bitcoin",
    symbol: "BTC",
    decimals: 18
  }
}

Contract Addresses

Architecture Overview

┌─────────────┐
│   Frontend  │  Next.js + Wagmi + Viem
│  (Port 9002)│  React Query + Zustand
└──────┬──────┘
       │
       ├─────────────┐
       ▼             ▼
┌─────────────┐  ┌──────────────┐
│  REST API   │  │ Smart        │
│ (Port 3001) │  │ Contracts    │
│  Express.js │  │ Mezo Testnet │
└──────┬──────┘  └──────┬───────┘
       │                │
       ▼                ▼
┌──────────────────────────┐
│   PostgreSQL Database    │
│   - User data            │
│   - Indexed events       │
│   - Pool metadata        │
└──────────────────────────┘
       ▲
       │
┌──────┴──────┐
│   Indexer   │  ethers.js event listeners
│  (Service)  │  Real-time blockchain sync
└─────────────┘

Learn more →

Developer Resources

Documentation Sections

NPM Packages

KhipuVault uses a monorepo structure with these packages:

@khipu/web3        # ABIs, contract addresses, type definitions
@khipu/database    # Prisma client (PostgreSQL)
@khipu/shared      # Shared types, constants, utilities
@khipu/ui          # React components (Radix/shadcn)

Currently for internal use. Public npm packages coming soon.

Getting Started

5-Minute Integration

1. Install Dependencies

   npm install wagmi viem @tanstack/react-query

2. Configure Wagmi

   import { createConfig, http } from 'wagmi'
   import { mezoTestnet } from './chains'
   
   export const config = createConfig({
     chains: [mezoTestnet],
     transports: {
       [mezoTestnet.id]: http('https://rpc.test.mezo.org')
     }
   })

3. Make Your First Contract Call

   import { useReadContract } from 'wagmi'
   import { INDIVIDUAL_POOL_ABI } from '@khipu/web3'
   
   const { data: balance } = useReadContract({
     address: '0xdfBEd2D3efBD2071fD407bF169b5e5533eA90393',
     abi: INDIVIDUAL_POOL_ABI,
     functionName: 'balanceOf',
     args: [userAddress]
   })

Full Quickstart →

Common Use Cases

Read Pool Data

// Get user's savings balance
const balance = await readContract({
  address: INDIVIDUAL_POOL_ADDRESS,
  abi: INDIVIDUAL_POOL_ABI,
  functionName: 'balanceOf',
  args: [userAddress]
})

Make a Deposit

// Deposit 100 MUSD
const { hash } = await writeContract({
  address: INDIVIDUAL_POOL_ADDRESS,
  abi: INDIVIDUAL_POOL_ABI,
  functionName: 'deposit',
  args: [parseUnits('100', 18)]
})

Query API

// Get pool analytics
const response = await fetch('https://api.khipuvault.com/pools/individual')
const data = await response.json()

More Examples →

Support & Community

Contributing

KhipuVault is open source! Contributions welcome:

• Smart Contracts: Security audits, gas optimization
• Frontend: UI improvements, new features
• Backend: API endpoints, event indexing
• Documentation: Guides, examples, translations

See our Contributing Guide

Roadmap

Q1 2026

• Mainnet launch on Mezo
• Public npm packages
• GraphQL API
• Subgraph indexing

Q2 2026

• SDK libraries (TypeScript, Python)
• Webhook notifications
• Advanced analytics API

Next Steps

Ready to build? Start with our Quickstart Guide or explore the Smart Contracts.