Development Guide

Guide for building, testing, and deploying the Rate Swap Protocol.

Prerequisites

Required Tools

Rust: 1.75 or later
Solana CLI: 1.18 or later
Anchor CLI: 0.32.1 or later
Node.js: 18 or later
Yarn: 1.22 or later

Installation

bash

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Solana CLI
sh -c "$(curl -sSfL https://release.solana.com/stable/install)"

# Install Anchor
cargo install --git https://github.com/coral-xyz/anchor avm --locked --force
avm install 0.32.1
avm use 0.32.1

# Install Node.js dependencies
cd rate-swap
yarn install

Project Structure

rate-swap/                       # Root directory
├── rate-swap/                   # Anchor project
│   ├── programs/rate-swap/src/  # Solana program (Rust)
│   ├── tests/                   # TypeScript tests
│   ├── Anchor.toml              # Anchor config
│   ├── Cargo.toml               # Rust dependencies
│   └── package.json             # Node dependencies
├── .deps/rate-swap-amm/         # Git submodule (AMM crate)
├── docs/                        # Documentation (this site)
├── CLAUDE.md                    # AI assistant instructions
└── README.md                    # Project README

Build Process

Build the Program

All build commands should be run from the rate-swap/ subdirectory:

bash

cd rate-swap

# Build the Solana program
anchor build

# Or use Makefile
make build

Output: Compiled program in target/deploy/rate_swap.so

Generate IDL

bash

# IDL generated automatically during build
# Location: target/idl/rate_swap.json

Check Build Success

bash

# Verify program compiled
ls -lh target/deploy/rate_swap.so

# Check program ID
solana-keygen pubkey target/deploy/rate_swap-keypair.json
# Should output: CPrPi4AnqM2RhQXZ9n7gyWb4i7BcTJDDWruhonuRU1jc

Development Workflow

1. Make Code Changes

Edit files in programs/rate-swap/src/

2. Format Code

bash

# Check formatting
make fmt_check

# Auto-fix formatting
make fmt

3. Build

bash

anchor build

4. Run Tests

bash

# Run all tests (starts local validator)
anchor test

# Run specific test file
yarn run ts-mocha -p ./tsconfig.json -t 1000000 "tests/pool_nav.ts"

# Run tests with logs
anchor test -- --nocapture

5. Lint/Check

bash

# Run all CI checks
make check

# This runs:
# - cargo fmt --check
# - cargo clippy
# - anchor build

Testing

Local Validator

Anchor tests automatically start a local validator. You can also start one manually:

bash

# Start local validator
solana-test-validator

# In another terminal, set config
solana config set --url localhost

# Check validator is running
solana cluster-version

Running Tests

bash

# All tests
anchor test

# Specific test file
yarn run ts-mocha -p ./tsconfig.json -t 1000000 "tests/init_market.ts"

# With verbose output
RUST_LOG=solana_runtime::system_instruction_processor=trace,solana_runtime::message_processor=debug,solana_bpf_loader=debug,solana_rbpf=debug anchor test

Test Files

Located in rate-swap/tests/:

pool_nav.ts - Pool NAV and share accounting tests
init_market.ts - Market initialization tests
liquidity_depth.ts - Liquidity routing tests
liquidation.ts - Liquidation logic tests
oracle.ts - Oracle staleness and update tests

Writing New Tests

typescript

import * as anchor from '@coral-xyz/anchor';
import { Program } from '@coral-xyz/anchor';
import { RateSwap } from '../target/types/rate_swap';
import { expect } from 'chai';

describe('my-test', () => {
  const provider = anchor.AnchorProvider.env();
  anchor.setProvider(provider);

  const program = anchor.workspace.RateSwap as Program<RateSwap>;

  it('should do something', async () => {
    // Test logic here
  });
});

Deployment

Devnet Deployment

bash

# Set cluster to devnet
solana config set --url devnet

# Ensure you have SOL for deployment
solana balance
# If low, airdrop some
solana airdrop 2

# Deploy program
anchor deploy

# Verify deployment
solana program show <PROGRAM_ID>

Mainnet Deployment

CRITICAL: Only deploy after thorough audits and testing

bash

# Set cluster to mainnet
solana config set --url mainnet-beta

# Ensure sufficient SOL for deployment
solana balance

# Deploy (use --program-id for consistent address)
anchor deploy --provider.cluster mainnet

# Verify
solana program show CPrPi4AnqM2RhQXZ9n7gyWb4i7BcTJDDWruhonuRU1jc

Program Upgrades

bash

# Build new version
anchor build

# Upgrade on devnet
anchor upgrade target/deploy/rate_swap.so --program-id CPrPi4AnqM2RhQXZ9n7gyWb4i7BcTJDDWruhonuRU1jc

# For mainnet, use multi-sig and timelock (governance)

Configuration

Anchor.toml

toml

[programs.localnet]
rate_swap = "CPrPi4AnqM2RhQXZ9n7gyWb4i7BcTJDDWruhonuRU1jc"

[programs.devnet]
rate_swap = "CPrPi4AnqM2RhQXZ9n7gyWb4i7BcTJDDWruhonuRU1jc"

[programs.mainnet]
rate_swap = "CPrPi4AnqM2RhQXZ9n7gyWb4i7BcTJDDWruhonuRU1jc"

[provider]
cluster = "localnet"
wallet = "~/.config/solana/id.json"

[test]
startup_wait = 10000

Cargo.toml

toml

[dependencies]
anchor-lang = "0.32.1"
anchor-spl = "0.32.1"

[dev-dependencies]
# Test dependencies

[features]
# Feature flags

Git Submodules

The .deps/rate-swap-amm/ directory is a git submodule.

bash

# Initialize submodules (first time)
git submodule update --init --recursive

# Update submodules
git submodule update --remote

# Check submodule status
git submodule status

Debugging

Common Issues

Issue: Build fails with "program ID mismatch"

Solution: Ensure declare_id! in lib.rs matches deployed program

Issue: Tests timeout

Solution: Increase timeout in test command:

bash

yarn run ts-mocha -p ./tsconfig.json -t 1000000 "tests/test.ts"

Issue: Anchor version mismatch

Solution: Check and align versions:

bash

anchor --version
# Ensure matches version in Anchor.toml and package.json

Logging

Add debug logging in Rust:

rust

use anchor_lang::prelude::*;

msg!("Debug value: {}", my_value);

View logs during tests:

bash

anchor test -- --nocapture

CI/CD

GitHub Actions workflow in .github/workflows/:

yaml

- name: Build
  run: cd rate-swap && make build

- name: Test
  run: cd rate-swap && anchor test

- name: Lint
  run: cd rate-swap && make check

IDE Setup

VS Code

Recommended extensions:

rust-analyzer
Even Better TOML
Prettier

.vscode/settings.json:

json

{
  "rust-analyzer.cargo.features": "all",
  "editor.formatOnSave": true
}

Best Practices

Always run tests before committing
Format code with make fmt
Check with clippy via make check
Update tests when changing logic
Document complex logic in code comments
Use checked arithmetic to prevent overflow
Validate PDAs on-chain
Test edge cases (zero values, max values, etc.)

Next Steps

Testing - Detailed test documentation
API Reference - Client API usage
Smart Contracts - Contract internals

Development Guide ​

Prerequisites ​

Required Tools ​

Installation ​

Project Structure ​

Build Process ​

Build the Program ​

Generate IDL ​

Check Build Success ​

Development Workflow ​

1. Make Code Changes ​

2. Format Code ​

3. Build ​

4. Run Tests ​

5. Lint/Check ​

Testing ​

Local Validator ​

Running Tests ​

Test Files ​

Writing New Tests ​

Deployment ​

Devnet Deployment ​

Mainnet Deployment ​

Program Upgrades ​

Configuration ​

Anchor.toml ​

Cargo.toml ​

Git Submodules ​

Debugging ​

Common Issues ​

Logging ​

CI/CD ​

IDE Setup ​

VS Code ​

Best Practices ​

Next Steps ​

Development Guide

Prerequisites

Required Tools

Installation

Project Structure

Build Process

Build the Program

Generate IDL

Check Build Success

Development Workflow

1. Make Code Changes

2. Format Code

3. Build

4. Run Tests

5. Lint/Check

Testing

Local Validator

Running Tests

Test Files

Writing New Tests

Deployment

Devnet Deployment

Mainnet Deployment

Program Upgrades

Configuration

Anchor.toml

Cargo.toml

Git Submodules

Debugging

Common Issues

Logging

CI/CD

IDE Setup

VS Code

Best Practices

Next Steps