Development Setup

Set up your local development environment for Sable Protocol

This guide will help you set up a local development environment to build, test, and contribute to Sable Protocol.

Prerequisites

Before you begin, ensure you have the following installed:

Tool	Version	Purpose
Node.js	≥ 20.x	JavaScript runtime for Next.js
npm	≥ 10.x	Package manager
Scarb	≥ 2.13.1	Cairo package manager and build tool
Cairo	2.14.0	Smart contract language compiler
StarkNet Wallet	Latest	Argent X or Braavos browser extension

Installing Scarb

Scarb is the Cairo package manager. Install it using:

macOS/Linux

curl --proto '=https' --tlsv1.2 -sSf https://docs.swmansion.com/scarb/install.sh | sh

Verify installation:

scarb --version
# Should output: scarb 2.14.0

Installation

1. Clone the Repository

   git clone <repo-url> sable
   cd sable
   
2. Install Dependencies

   npm

   npm install
   
3. Set Up Environment Variables

   Create a .env.local file in the root directory:

   # StarkNet RPC endpoints
   NEXT_PUBLIC_STARKNET_RPC=https://rpc.starknet.lava.build
   STARKNET_RPC=https://starknet-mainnet.g.alchemy.com/starknet/version/rpc/v0_8/<your-key>
   
   # Curator credentials (for /api/curator endpoint)
   CURATOR_PRIVATE_KEY=0x...
   CURATOR_ADDRESS=0x...
   
   # Keeper credentials (for DCA keeper bot)
   KEEPER_KEY=0x...
   KEEPER_ADDR=0x...
   

   Never commit .env.local to version control. It contains sensitive private keys.

4. Build Cairo Contracts

   cd contracts
   scarb build
   

   This generates Sierra and CASM files in contracts/target/

Running the Development Server

Start the Next.js development server with Turbopack:

npm run dev

The application will be available at http://localhost:3000 with:

• Hot module replacement
• Fast refresh
• Real-time error overlay

Building for Production

1. Build the Application

   npm run build
   

   This creates an optimized production build in .next/

2. Start the Production Server

   npm start
   

   The production server will run on http://localhost:3000

Project Structure

Understanding the directory structure:

sable/
├── contracts/               # Cairo smart contracts
│   ├── src/
│   │   ├── sentinel.cairo  # Vault contracts
│   │   ├── citadel.cairo
│   │   ├── trident.cairo
│   │   ├── delta_neutral.cairo
│   │   ├── btcvault.cairo  # Turbo vault
│   │   ├── apex.cairo
│   │   ├── dca.cairo       # DCA contract
│   │   ├── cdp.cairo       # CDP contract
│   │   └── shielded_pool_v4.cairo  # Privacy pools
│   ├── Scarb.toml          # Cairo dependencies
│   └── scripts/            # Deploy/upgrade scripts
│
├── src/
│   ├── app/                # Next.js pages
│   │   ├── page.tsx        # Home (vault listing)
│   │   ├── vault/[id]/     # Vault details
│   │   ├── privacy/        # Shielded vaults
│   │   ├── dca/            # Dollar-cost averaging
│   │   ├── cdp/            # Collateralized debt
│   │   ├── stake/          # Direct staking
│   │   ├── bridge/         # Cross-chain bridge
│   │   └── portfolio/      # User dashboard
│   │
│   ├── components/         # React components
│   ├── hooks/             # Custom React hooks
│   ├── lib/               # Utilities and APIs
│   │   ├── api/          # External API integrations
│   │   ├── privacy/      # ZK proof generation
│   │   └── abi/          # Contract ABIs
│   └── providers/         # React context providers
│
├── scripts/               # Off-chain tools
│   └── dca_keeper.mjs    # DCA execution bot
│
└── public/               # Static assets

Working with Smart Contracts

Compiling Contracts

cd contracts
scarb build

Output files are generated in contracts/target/dev/:

• .sierra.json - Sierra intermediate representation
• .casm.json - Compiled Assembly (CASM) for StarkNet

Deploying Contracts

node contracts/scripts/deploy.mjs

Upgrading Contracts

Sable contracts are upgradeable. To upgrade:

# Standard upgrade
node contracts/scripts/upgrade.mjs

# CDP-specific upgrade (with proper resource bounds)
node contracts/scripts/upgrade-cdp.mjs

Running the DCA Keeper Bot

The keeper bot executes due DCA orders automatically:

node scripts/dca_keeper.mjs

For production, set up a cron job to run the keeper every 6 hours:

0 */6 * * * cd /path/to/sable && node scripts/dca_keeper.mjs >> /var/log/dca_keeper.log 2>&1

Development Workflow

1. Make Changes

   Edit frontend code in src/ or Cairo contracts in contracts/src/

2. Test Locally

   • Frontend: Changes hot-reload automatically
   • Contracts: Rebuild with scarb build and redeploy
3. Lint Code

   npm run lint
   
4. Build for Production

   npm run build
   

   Verify there are no build errors

Connecting to StarkNet

The application uses the default Lava free RPC endpoint:

https://rpc.starknet.lava.build

For better performance, consider:

• Alchemy StarkNet API
• Infura StarkNet
• Running your own StarkNet node

Common Commands

Command	Description
npm run dev	Start development server (Turbopack)
npm run build	Build for production
npm start	Start production server
npm run lint	Run ESLint
scarb build	Compile Cairo contracts
scarb test	Run Cairo tests

Troubleshooting

Having issues? Check the Troubleshooting guide for common problems and solutions.

Next Steps

Architecture

Learn about Sable’s technical architecture

Smart Contracts

Explore the Cairo smart contracts

API Reference

Review API endpoints and usage

Testing

View on-chain testing evidence