vela-sdk

Developer-facing client and CLI layer for the Vela protocol. Published as @velapay/sdk on npm. Some internal app repos import it through the local alias @vela/sdk while linked to the sibling SDK repo.

Purpose and Role

The connective tissue between protocol and product surfaces:

• Exposes Commerce OS namespaces for Payment Intents and merchant-signed refunds, plus the one-time checkout.create() alias.
• Exposes a high-level API for plans, subscriptions, pulls, streams, upgrades, and agent mandates.
• Ships 36 instruction builders in src/instructions/ covering every protocol entry point (periodic, streaming, agent, admin, config, Arcium request paths, wrap/unwrap).
• Ships 40+ typed error classes across src/errors/ (program, SDK, stream, upgrade, X.402) with translate.ts mapping raw program errors to typed JS exceptions.
• Centralizes PDA derivation in PDAFactory (single source of truth) — covers all account types (Plan, Mandate, StreamMandate, PullApproval, Credential, TokenConfig, AgentMandate, ProtocolConfig, Arcium computation accounts).
• Ships the vela CLI binary at bin/vela (built on commander) for local testing and operator workflows.
• Carries the protocol IDL into downstream consumers.
• Integrates @arcium-hq/client 0.9.3 for encrypted-input request paths (request-validation, request-usage-computation, request-billing-record).
• Implements the X.402 payment protocol surface (src/x402/{client,server,proof,nonce-cache}.ts).

Subpath Exports

@velapay/sdk ships ten public subpath exports for tree-shaking and browser-safety:

Subpath	Purpose
@velapay/sdk	Default barrel — full Node-compatible API
@velapay/sdk/browser	Browser-safe barrel (no Node-only deps) for widget and checkout
@velapay/sdk/accounts	Anchor account deserializers
@velapay/sdk/instructions	Raw instruction builders
@velapay/sdk/events	Zod-typed event schemas (consumed by @vela/webhook)
@velapay/sdk/errors	Typed error classes + translate()
@velapay/sdk/protocol	Program IDs, PDA seeds, IDL re-export
@velapay/sdk/security	Signature/HMAC helpers
@velapay/sdk/token	Token-2022 helpers, formatAmount, parseAmount, TokenConfig resolver
@velapay/sdk/inspection	Read-only protocol-state inspection helpers
@velapay/sdk/x402	X.402 client/server, proof, nonce cache

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

Tech Stack

Technology	Version	Purpose
Bun	1.3.x	Runtime + package manager
TypeScript	5.8.x	Language (5.8 chosen for helius-sdk peer constraint; app repos run on 6.0.2)
@solana/web3.js	^1.98.x	Solana client (required by @coral-xyz/anchor v1)
@solana/spl-token	0.4.14	Token-2022 TypeScript helpers
@coral-xyz/anchor	0.32.1	Anchor TS client — exact-pin to match deployed program IDL
@arcium-hq/client	0.9.3	Arcium MXE client — encrypts inputs, decrypts callback payloads
helius-sdk	2.2.x	RPC, webhooks, DAS API
Zod	^3.x	Event schema validation (@velapay/sdk/events)
commander	latest	CLI argument parsing for bin/vela

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               # @velapay/sdk
└── tsconfig.json

Deployment Target

• npm: Published as @velapay/sdk with CommonJS + ESM dual output.
• Consumers: Public consumers install @velapay/sdk; some local product repos alias the sibling workspace as @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	@velapay/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.
• v1.9 Commerce SDK published: @velapay/sdk@0.5.0 with paymentIntents, refunds, checkout.create, commerce lifecycle types, receipt/credit-note references, CommerceApiError, and commerce event schemas.
• Browser-safe boundary: @velapay/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

@velapay/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)

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

Commerce events use snake_case fields and UUID event IDs. The v1.9 set covers Payment Intent creation, confirmation, and expiry plus refund creation, confirmation, and failure.

Version Compatibility

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