Swarm Vault

A platform that enables managers to execute transactions on behalf of multiple users on Base blockchain. Users join "swarms" managed by trusted managers, and each user gets a ZeroDev smart wallet that the swarm's Lit Protocol PKP can sign transactions for.

Features

• Swarm Management: Create and manage swarms with multiple members
• Smart Wallets: ZeroDev Kernel v3 smart wallets for each member
• Transaction Templating: Execute parameterized transactions across all swarm members
• Token Swaps: Integrated 0x DEX aggregator for optimal swap routing
• Balance Tracking: Real-time balance display via Alchemy
• Withdrawals: Users can withdraw funds directly from their agent wallets
• Manager SDK: TypeScript SDK for programmatic trading (@swarmvault/sdk)
• API Documentation: Interactive API docs at /api/docs

Tech Stack

• Frontend: Vite + React + TypeScript + TailwindCSS
• Backend: Express + TypeScript
• Database: PostgreSQL + Prisma
• Monorepo: pnpm workspaces
• Blockchain: Base (Sepolia for dev, Mainnet for prod)
• Smart Wallets: ZeroDev (Kernel v3)
• Signing: Lit Protocol PKP + Lit Actions
• Wallet Connection: wagmi + viem
• Balance Indexing: Alchemy

Prerequisites

• Node.js >= 18.0.0
• pnpm >= 8.0.0
• PostgreSQL 14+
• Lit Protocol account (for PKP minting)
• ZeroDev account (project ID)
• Alchemy account (API key)
• 0x account (API key)

Quick Start

1. Clone and Install

git clone <repository-url>
cd swarm-vault
pnpm install

2. Configure Environment Variables

cp .env.example .env

Edit .env with your credentials:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/swarm_vault

# Lit Protocol
LIT_NETWORK=datil-dev
LIT_PRIVATE_KEY=0x...  # EOA for subsidizing Lit costs

# ZeroDev
ZERODEV_PROJECT_ID=your-project-id

# Chain (84532 = Base Sepolia, 8453 = Base Mainnet)
CHAIN_ID=84532

# Alchemy
ALCHEMY_API_KEY=your-alchemy-api-key

# 0x DEX Aggregator
ZEROX_API_KEY=your-0x-api-key

# Auth
JWT_SECRET=your-jwt-secret-at-least-32-characters

# Server
PORT=3001
NODE_ENV=development

# Client (for Vite)
VITE_API_URL=http://localhost:3001
VITE_CHAIN_ID=84532
VITE_ZERODEV_PROJECT_ID=your-project-id

3. Set Up Database

pnpm db:migrate

4. Run Development Servers

pnpm dev

This starts both the client (port 5173) and server (port 3001).

Project Structure

swarm-vault/
├── packages/
│   ├── client/          # Vite + React frontend
│   ├── server/          # Express backend
│   ├── shared/          # Shared types, utils, constants
│   ├── sdk/             # TypeScript SDK for managers (@swarmvault/sdk)
│   └── lit-actions/     # Lit Action source code
├── prisma/
│   └── schema.prisma    # Database schema
├── .env.example
├── package.json
└── pnpm-workspace.yaml

Environment Variables

Server Variables

Client Variables (Vite)

Programmatic Access for Managers

Managers can programmatically execute swaps and transactions on behalf of their swarm members. There are two options:

Option 1: TypeScript SDK (Recommended for JS/TS projects)

Install the SDK:

npm install @swarmvault/sdk

Quick example:

import { SwarmVaultClient, BASE_MAINNET_TOKENS } from '@swarmvault/sdk';

const client = new SwarmVaultClient({
  apiKey: 'svk_your_api_key_here', // Get from Settings page
});

// Check holdings
const holdings = await client.getSwarmHoldings('swarm-id');

// Execute a swap (50% USDC to WETH)
const result = await client.executeSwap('swarm-id', {
  sellToken: BASE_MAINNET_TOKENS.USDC,
  buyToken: BASE_MAINNET_TOKENS.WETH,
  sellPercentage: 50,
});

// Wait f

...