Velocity Protocol v1 is a Solana perpetuals and spot trading protocol. This monorepo holds the
on-chain programs, the TypeScript and Rust SDKs, the admin CLI, and the deployable keeper and DLOB
services.
Integrating against the protocol? Start with the [SDK guide](./packages/sdk/README.md). If you are
migrating from the Drift SDK, read [docs/DRIFT-TO-VELOCITY.md](./docs/DRIFT-TO-VELOCITY.md) as well.
## Repository map
| Path | What it is |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `programs/` | On-chain programs: `velocity` (core protocol), `vaults`, `jit-proxy`, plus oracle stubs and integrations used by tests |
| `packages/` | Publishable npm libraries: `@velocity-exchange/sdk`, `admin-cli`, `vaults-sdk`, `jit-proxy` |
| `apps/` | Private deployable services, shipped as Docker images and never to npm: `dlob-server`, `keeper-bots-v2`, `usermap-server` |
| `rust/` | A second, separate Cargo workspace: `velocity-rs` (Rust SDK), `keep-rs` (keeper bots), `swift` (tx server) |
| `tests/` | ~120 TypeScript integration test files. Nearly all run in-process on LiteSVM; a handful use a local validator |
| `deploy-scripts/` | Devnet build, deploy, wipe and init runbooks. See [deploy-scripts/README.md](./deploy-scripts/README.md) |
| `docs/` | Deep-dive docs. See [Further reading](#further-reading) |
The two Cargo workspaces are deliberately separate. The root workspace builds the on-chain programs
for SBF. The `rust/` workspace consumes the program as a host library, with its own lockfile and its
own `rust/target/`, so its split solana 4.2 crate tree never unifies with the SBF build.
## Deployments
| Program | ID |
| ----------- | ---------------------------------------------- |
| `velocity` | `vELoC1audYbSYVRXn1vPaV8Axoa9oU6BYmNGZZBDZ1P` |
| `vaults` | `vAuLTsyrvSfZRuRB3XgvkPwNGgYSs9YRYymVebLKoxR` |
| `jit-proxy` | `J1TPRoXCtGuMcWiWFE6RB9eZU8U35PBMETCwNQLCNPhQ` |
## Prerequisites
| Tool | Version | Notes |
| --------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------- |
| Rust | ≥ 1.89 | The Anchor 1.0 MSRV. CI pins 1.91.1 in `RUST_TOOLCHAIN`. Develop on ≥ 1.77 so the 16-byte `u128` alignment guards fire locally |
| Rust nightly (rustfmt only) | any recent | `rustup toolchain install nightly --component rustfmt`. Formatting only; builds, clippy and tests stay on stable |
| Solana CLI | ≥ 4.3 | Needed for a `cargo-build-sbf` that can emit SBPFv3. 4.2.2 ships 4.1.0, which cannot. CI pins `4.3.0` |
| Solana platform-tools | ≥ v1.56 | The SBPFv3 minimum; the repo pins v1.57. Older versions also cannot parse `edition2024` dependencies. See [Troubleshooting](#troubleshooting) |
| Anchor CLI | 1.0.2 | Used for the IDL only. The `.so` is built by `deploy-scripts/build-sbf.sh`, because Anchor pins its own platform-tools |
| Bun | ≥ 1.x | The only supported JS package manager here, not yarn or npm. The repo pins `bun@1.3.14` in `packageManager` |
On Apple Silicon, always use the x86_64 cross-compile toolchain, never a native aarch64 one. Native
ARM toolchains break the memory-layout expectations of zero-copy accounts, which must match the
on-chain x86_64 representation:
```bash
rustup default stable-x86_64-apple-darwin
```
macOS also needs the SDK path exported for the platform-tools clang. Add this to your shell profile:
```bash
export SDKROOT="$(xcrun --show-sdk-path)"
```
And install the platform-tools the repo pins, once:
```bash
cargo-build-sbf --install-only --tools-version v1.57
```
`~/.cargo/bin` must come before `/opt/homebrew/bin` on PATH. `cargo-build-sbf` and `anchor idl build`
both shell out to `cargo +`, which only works when `cargo` is the rustup shim.
## Quick start
```bash
git clone https://github.com/velocity-exchange/velocity-v1.git && cd velocity-v1
# install ALL workspace deps, once, at the repo root (never inside individual packages)
bun install
# build the program and sync the IDL + types into packages/sdk
bun run program:build
# run the Rust unit tests
cargo test -p velocity
# build the whole TypeScript workspace (turbo, dependency order)
bun run build
# run the full integration suite (73 files; builds the .so first)
bash test-scripts/run-anchor-tests.sh
# same suite in one process instead of one per file: 53s -> 19s
SINGLE_PROCESS=1 bash test-scripts/run-anchor-tests.sh --skip-build
```
The programs build for SBPFv3, which SIMD-0500 makes the only deployable bytecode format from Agave
v4.4 on. `deploy-scripts/build-sbf.sh` owns the bytecode version, the platform-tools version and the
per-program feature flags, and every build path routes through it. See
[`docs/sbpfv3-migration.md`](./docs/sbpfv3-migration.md).
## Fuzzing
The fuzz harnesses for the program live in [`fuzz/`](./fuzz/README.md), built on
[Crucible](https://github.com/asymmetric-research/crucible). They are a separate set of Cargo
workspaces and never ship on-chain.
```bash
# install the Crucible CLI at the pinned rev
cargo install --git https://github.com/asymmetric-research/crucible \
--rev daeaa4d4a4e334175c4f171daacc7e177ad2fae0 crucible-fuzz-cli --locked
# host tier (pure math)
crucible run amm-pricing prop_k_conserved_swap --timeout 30
# svm tier (needs a devnet .so from `bun run program:build:devnet`)
crucible run e2e-svm invariant_solvency --release --timeout 60
```
The SVM harnesses read `packages/sdk/src/idl/velocity.json` directly, so a program change needs no
extra sync step. [`fuzz/README.md`](./fuzz/README.md) has the harness list and the details.
## Common tasks
| Task | Command |
| --------------------------------------------- | -------------------------------------------------------------------------- |
| Build program + sync IDL/types into the SDK | `bun run program:build` |
| Regenerate IDL/types only (fast, no SBF build) | `bun run program:idl` (vaults: `program:idl:vaults`, jit: `program:idl:jit-proxy`) |
| Deployable devnet `.so` | `bun run program:build:devnet` |
| Mainnet `.so` (production gates on) | `bun run program:build:mainnet` |
| Build one TS package + its deps | `bunx turbo run build --filter=@velocity-exchange/sdk` |
| Build the `rust/` workspace | `bun run rust:build` (or `cargo check --manifest-path rust/Cargo.toml`) |
| Rust unit tests | `cargo test -p velocity` (add `-- --show-output` for stdout) |
| One integration test | `ts-mocha -t 300000 ./tests/.ts` |
| Full integration suite (skip rebuild) | `bash test-scripts/run-anchor-tests.sh --skip-build` |
| SDK unit tests | `cd packages/sdk && bun run test:ci` (DLOB: `bun run test:dlob`) |
| Rust lint/format | `bun run fmt:rust && cargo clippy -p velocity` (CI enforces both) |
| SDK lint/format | `cd packages/sdk && bun run prettify:fix && bun run lint` |
Three habits save a lot of pain here.
- Format Rust with `bun run fmt:rust`, never with plain `cargo fmt`. `rustfmt.toml` merges all of a
module's imports into a single `use { ... }` block using nightly-only options. Stable `cargo fmt`
ignores those options, so imports you add stay unmerged and CI's nightly check fails. The script
wraps nightly rustfmt across every Rust codebase in the repo: the program workspace, the `rust/`
workspace, the fuzz crates, and the examples. `bun run fmt:rust:check` verifies without writing.
Format-on-save is preconfigured in the committed `.vscode/settings.json` (VS Code and Cursor) and
`.zed/settings.json` (Zed), both of which point rust-analyzer's rustfmt at nightly. Generated code
(`velocity_idl.rs`) and vendored code are excluded on purpose.
- Never hand-edit generated artifacts. `packages/sdk/src/idl/velocity.json`, its `velocity.ts`
sibling, and `rust/velocity-rs/crates/src/velocity_idl.rs` are all generated from the Rust
program. Change the program, then run `bun run program:build`, or `bun run program:idl` for the
fast path.
- Treat `packages/sdk/src/types.ts` as a hand-maintained mirror of the on-chain structs. When a
struct, account or event changes in the program, update the mirror in the same change.
## Troubleshooting
**`fatal error: 'assert.h' file not found` during `anchor build` (macOS).**
The platform-tools clang has no built-in macOS SDK path. Run
`export SDKROOT="$(xcrun --show-sdk-path)"`, and put it in your shell profile.
**`feature 'edition2024' is required ... not stabilized in this version of Cargo (1.84.0)`.**
The bundled cargo in older platform-tools cannot parse `edition2024` dependencies. Install the
pinned toolchain once with `cargo-build-sbf --install-only --tools-version v1.57`, then verify with
`cargo-build-sbf --version`.
**`error: no such command: \`+stable\`` or `+1.95.0-sbpf-solana-v1.57`.**
A homebrew cargo at `/opt/homebrew/bin/cargo` is ahead of the rustup shim on PATH and does not
understand `+toolchain`. Put `~/.cargo/bin` first.
**Runtime panic `Access violation in unknown section at address 0x...` on instructions touching
types you did not change.**
This is almost always stale SBF build artifacts after a `Cargo.lock` change, such as a `cargo update`
or a branch switch onto a different lockfile. The cache key misses some dependency-resolution
changes, and the resulting `.so` reads the wrong offsets. Fix it with:
```bash
rm -rf target/sbpf*-solana-solana target/deploy
bash deploy-scripts/build-sbf.sh test
```
**Zero-copy layout or `const_assert_eq!` failures on Apple Silicon.**
You are on a native aarch64 toolchain. Switch with `rustup default stable-x86_64-apple-darwin`.
## Dev container (alternative)
If you would rather not install the toolchain locally, `.devcontainer/` ships a Dockerfile and a
docker-compose file with pinned Rust, Solana and Anchor versions. Use your IDE's "Reopen in
Container", or:
```bash
cd .devcontainer && docker compose up -d && docker compose exec velocity bash
```
## Releases
This monorepo uses [changesets](https://github.com/changesets/changesets) to version and publish the
library packages under `packages/*`. Apps under `apps/*` are `private` and ship as Docker images
built from `docker-info.json` by the `velocity-publish` workflow, not to npm.
1. In a PR that changes a publishable package, run `bun run changeset` and describe the bump.
2. On merge to `master`, the `changesets` workflow opens or updates a "Version Packages" PR that
runs `changeset version`, bumping versions and writing CHANGELOGs. Merge it to commit the bumps.
3. Push a per-package tag `npm--v`. The `npm-publish` workflow builds and publishes
that package through npm OIDC trusted publishing. It is idempotent, and skips the publish if that
version is already on the registry. `` is the directory name under `packages/`:
| Package | Tag example |
| ------------------------------- | ----------------------- |
| `@velocity-exchange/sdk` | `npm-sdk-v0.2.3` |
| `@velocity-exchange/admin-cli` | `npm-cli-admin-v0.2.3` |
| `@velocity-exchange/vaults-sdk` | `npm-vaults-sdk-v0.2.3` |
| `@velocity-exchange/jit-proxy` | `npm-jit-proxy-v0.2.3` |
The tag version must match the `package.json` version committed by the "Version Packages" PR. Do not
edit `package.json` versions by hand; changesets and the bot own those fields.
## Further reading
| Doc | What's in it |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| [ARCHITECTURE.md](./ARCHITECTURE.md) | Execution flow maps, module responsibility matrix, SDK to program mappings |
| [docs/DRIFT-TO-VELOCITY.md](./docs/DRIFT-TO-VELOCITY.md) | The canonical record of every change vs upstream Drift. Read it if you are integrating |
| [docs/FEES.md](./docs/FEES.md) | The fee architecture: per-fill splits, fee ledger, sweeps, carveouts |
| [deploy-scripts/README.md](./deploy-scripts/README.md) | The devnet upgrade runbook: two-phase buffer deploys, wipe and reinit |
| [docs/alignment-and-native-offsets.md](./docs/alignment-and-native-offsets.md) | Zero-copy struct alignment invariants. Read before adding fields to accounts |
| [docs/ACCOUNT-EXTENSION.md](./docs/ACCOUNT-EXTENSION.md) | Growing zero-copy accounts past their padding: the `extend_account` crank, the migration runbook, the client rules |
| [docs/EXTERNAL-DEPENDENCIES.md](./docs/EXTERNAL-DEPENDENCIES.md) | Every external dependency of the on-chain programs. CPI targets, oracles, whitelisted venues, and the full transitive crate graph, each with its trust assumption and failure mode |
## Security and bug bounty
Do not open a GitHub issue to report a vulnerability. Email security@velocity.exchange, and see
[SECURITY.md](./SECURITY.md).
The bug bounty program's severity tiers, payouts, and scope are documented at
[docs.velocity.exchange/protocol/risk-and-safety/bug-bounty](https://docs.velocity.exchange/protocol/risk-and-safety/bug-bounty).