Skip to main content
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:
ToolVersionPurpose
Node.js≥ 20.xJavaScript runtime for Next.js
npm≥ 10.xPackage manager
Scarb≥ 2.13.1Cairo package manager and build tool
Cairo2.14.0Smart contract language compiler
StarkNet WalletLatestArgent X or Braavos browser extension

​
Installing Scarb

Scarb is the Cairo package manager. Install it using: 
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 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:

​
Common Commands

CommandDescription
npm run devStart development server (Turbopack)
npm run buildBuild for production
npm startStart production server
npm run lintRun ESLint
scarb buildCompile Cairo contracts
scarb testRun 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

Build docs developers (and LLMs) love

Get started for freeTalk to us