vela-sdk

Developer-facing client and CLI layer for the Vela protocol. Published as @vela/sdk on npm.

Purpose and Role

The connective tissue between protocol and product surfaces:

• Exposes a high-level API for plans, subscriptions, pulls, streams, upgrades, and agent mandates.
• Provides lower-level instruction builders and account derivation.
• Centralizes PDA derivation in PDAFactory (single source of truth).
• Ships the vela CLI for local testing and operator workflows.
• Carries the protocol IDL into downstream consumers.
• Includes @vela/sdk/events for typed webhook event schemas (Zod).
• Provides browser-safe barrel via @vela/sdk/browser.

If the SDK surface drifts, dashboard, checkout, portal, widget, webhook, and docs all drift with it.

Tech Stack

Technology	Version	Purpose
Bun	1.3.11	Runtime + package manager
TypeScript	5.8+	Language
@solana/web3.js	1.x	Solana client (Anchor compat)
@solana/spl-token	0.4.14	Token-2022 TypeScript helpers
@coral-xyz/anchor	0.32.1	Anchor TS client — generated from IDL
helius-sdk	2.2.2	RPC, webhooks, DAS API
Zod	latest	Event schema validation

Directory Structure

vela-sdk/
├── src/
│   ├── client.ts              # VelaClient — high-level API
│   ├── pdas.ts                # PDAFactory — centralized PDA derivation
│   ├── instructions/          # Instruction builders per operation
│   │   ├── create-plan.ts
│   │   ├── subscribe.ts
│   │   ├── execute-pull.ts
│   │   ├── execute-stream.ts      # v1.8
│   │   ├── upgrade.ts             # v1.8
│   │   ├── agent-mandate.ts       # v1.4
│   │   └── ...
│   ├── accounts/              # Account deserialization
│   │   ├── plan.ts
│   │   ├── mandate.ts
│   │   ├── stream-mandate.ts      # v1.8
│   │   ├── token-config.ts        # v1.7
│   │   └── ...
│   ├── events/                # Zod-typed event schemas
│   │   ├── mandate.ts
│   │   ├── pull.ts
│   │   ├── stream.ts              # v1.8
│   │   ├── plan-change.ts         # v1.8
│   │   └── index.ts
│   ├── utils/                 # Helpers
│   │   ├── format-amount.ts       # Token amount formatting via TokenConfig
│   │   ├── parse-amount.ts
│   │   └── accrued-now.ts         # v1.8 — real-time streaming accrual
│   ├── browser.ts             # Browser-safe barrel export
│   └── index.ts               # Full barrel export
├── cli/                       # vela CLI commands
│   ├── plan.ts
│   ├── subscribe.ts
│   └── ...
├── tests/                     # bun:test unit tests
├── idl/                       # Protocol IDL copy (synced from vela-protocol)
├── package.json               # @vela/sdk
└── tsconfig.json

Deployment Target

• npm: Published as @vela/sdk with CommonJS + ESM dual output.
• Consumers: All product repos import via bun add @vela/sdk.

Dependencies

What It Depends On

Dependency	Type	Purpose
vela-protocol	IDL	Instruction discriminators, account layouts, event definitions

What Depends on It

Consumer	What They Use
vela-dashboard	VelaClient, PDAFactory, instruction builders for all operations
vela-checkout	Subscribe instruction, PDAFactory for checkout transaction building
vela-portal	Cancel, upgrade instructions, mandate deserialization
vela-widget	Subscribe instruction (browser-safe barrel)
vela-webhook	@vela/sdk/events Zod schemas for typed event parsing
vela-synthetic	Full VelaClient for E2E validation
External developers	Public SDK for building on VelaPay

Current Status

• v1.8 complete: Streaming support, upgrade builders, multi-token helpers, accruedNow(), formatAmount/parseAmount.
• Browser-safe boundary: @vela/sdk/browser barrel with focused deserialization and instruction-byte stability tests.
• PDAFactory: Centralized derivation for all 7+ account types.

Notable Design Decisions

Centralized PDAFactory (v1.7)

Single source of truth for all PDA derivation. Every consumer uses the same seeds, same program ID, same derivation logic. If seeds change, only PDAFactory needs updating.

Browser-Safe Barrel

@vela/sdk/browser excludes Node.js-only dependencies (fs, crypto) for widget and checkout use in browser contexts. Instruction bytes are stability-tested to prevent drift.

accruedNow() (v1.8)

Real-time accrued streaming value computation client-side with zero RPC calls between settlements. Uses last_settled_ts and authorized_max_rate from the StreamMandate account.

Dual Output (CJS + ESM)

Published with both CommonJS and ESM entry points for compatibility with different module systems across consumers.

Event Schemas (Zod)

@vela/sdk/events provides Zod-typed discriminated union over all Vela events. Consumed by @vela/webhook for typed event delivery. CI enforces additive-only event evolution via schema-diff check.

Version Compatibility

SDK version must match protocol IDL exactly. Protocol updates require SDK rebuild and publish before consumers can update.