SDK Stack

@vela/sdk is the integration hinge for the rest of the workspace. Every app surface — dashboard, widget, checkout, portal — builds on the SDK for transaction construction, PDA derivation, and event parsing.

What It Is

Bun-built TypeScript package published to npm as @vela/sdk
Dual ESM/CJS output — works in Node, Bun, browsers, and Cloudflare Workers
CLI via vela bin — test mandates locally, inspect on-chain state, simulate billing cycles
Exports the protocol IDL alongside the code (./idl/vela_protocol.json)
Browser-safe barrel export — @vela/sdk/browser subpath strips Node-only dependencies
Event schema subpath — @vela/sdk/events for typed event parsing
x402 subpath — @vela/sdk/x402 for HTTP 402 adapter integration

Full SDK Architecture

vela-sdk/
├── src/
│   ├── index.ts              # Main barrel export
│   ├── client.ts             # VelaClient — primary SDK entry point
│   ├── constants.ts          # Program IDs, seeds, defaults
│   ├── idl.ts                # IDL re-export
│   ├── types.ts              # Shared TypeScript types
│   ├── errors/               # Typed error classes
│   │   ├── mandate-expired.ts
│   │   ├── pull-too-early.ts
│   │   ├── insufficient-funds.ts
│   │   └── agent-budget-exceeded.ts
│   ├── instructions/         # Instruction builders (38+ files)
│   │   ├── create-plan.ts
│   │   ├── subscribe.ts
│   │   ├── execute-pull.ts
│   │   ├── cancel.ts
│   │   ├── wrap-usdc.ts
│   │   ├── unwrap-usdc.ts
│   │   ├── stream/           # Stream engine instructions
│   │   └── agent/            # Agent mandate instructions
│   ├── accounts/             # Account deserialization helpers
│   ├── builders/             # High-level transaction builders
│   ├── validators/           # Preflight validation (check without submitting)
│   ├── events/               # Typed event parsing (24+ files)
│   │   └── index.ts          # Event barrel export
│   ├── browser/              # Browser-safe subpath
│   │   └── index.ts          # Strips Node-only deps (helius-sdk, etc.)
│   ├── x402/                 # HTTP 402 adapter
│   │   └── index.ts          # Mandate ↔ x402 translation
│   ├── token/                # Token-2022 helpers
│   │   └── wrap.ts           # wrap/unwrap USDC flows
│   ├── usage.ts              # Usage-based billing helpers
│   ├── schedule.ts           # Billing schedule computation
│   ├── proration/            # Proration math for plan switching
│   ├── portal-sessions.ts   # Customer portal session helpers
│   ├── helius/               # Helius-enhanced RPC path (optional)
│   └── accrued.ts            # Accrued amount computation for streams
├── cli/                      # CLI source
├── bin/vela                  # CLI entry point
├── idl/
│   └── vela_protocol.json   # Protocol IDL (exported as subpath)
├── tests/                    # SDK unit tests
├── build.ts                  # Custom Bun build script (dual ESM/CJS)
├── package.json
└── tsconfig.json

Important Dependencies with Versions

Package	Version	Why It's Here
`@coral-xyz/anchor`	0.32.1	Program client generation from IDL. Instruction building, account deserialization, event parsing. Must match deployed program.
`@solana/web3.js`	^1.98.4	Connection, transaction, and keystore primitives. Required by Anchor client.
`@solana/spl-token`	^0.4.14	Token-2022 helpers: create mint with extensions, transfer with hook resolution, get/set extra account metas.
`@arcium-hq/client`	0.9.3	Arcium encrypted instruction building. Used in the two-phase billing flow for mandate validation on ciphertext.
`commander`	^14.0.3	CLI interface. Powers `vela create-plan`, `vela subscribe`, `vela pull`, `vela simulate`, etc.
`hono`	^4.12.12	Used in x402 adapter middleware. Also used in portal session helpers.
`@x402/core`, `@x402/fetch`, `@x402/hono`, `@x402/svm`	^2.9.0	HTTP 402 payment protocol integration. Translate 402 headers to Vela mandates for agent billing.
`zod`	^4.3.6	Runtime type validation for API parameters and event schemas.
`decimal.js`	10.6.0	Precise decimal arithmetic for billing calculations (proration, usage, tier evaluation).
`helius-sdk`	^2.2.2 (optional peer)	Enhanced RPC path. Optional — SDK works without it, but with Helius you get webhook helpers and DAS API.

All Consumers Inside the Workspace

Consumer	Usage
`vela-dashboard`	Merchant product flows: plan creation, subscriber management, analytics via SDK methods
`vela-admin`	Protocol operator actions: admin-level mandate inspection, protocol config
`vela-widget`	Checkout transaction building in the iframe: `subscribe()`, `wrapAndSubscribe()`
`vela-checkout`	Hosted checkout at `pay.velapay.com`: session-based mandate creation, wallet connection
`vela-portal`	Customer portal at `portal.velapay.com`: subscription management, cancellation, plan switching
`vela-webhook`	Event parsing: typed event schemas from `@vela/sdk/events` for webhook payload processing
`vela-docs`	SDK reference documentation and code examples
`vela-protocol` (ts-tests)	Integration tests using SDK client against LiteSVM provider

Build + Package Shape

The custom build.ts script produces:

Output	Path	Purpose
ESM	`dist/esm/src/`	Primary module format. Tree-shakeable. Used by Bun, Vite, and modern bundlers.
CommonJS	`dist/cjs/src/`	Legacy compatibility. Used by older Node tools and some Worker environments.
CLI	`bin/vela`	CLI entry point. Runs with `bun` or `node`.
IDL	`idl/vela_protocol.json`	Protocol IDL. Exported as `@vela/sdk/idl/vela_protocol.json`.

Package Exports Map

json

{
  ".": { "import": "ESM", "require": "CJS" },
  "./x402": { "import": "ESM", "require": "CJS" },
  "./events": { "import": "ESM", "require": "CJS" },
  "./browser": { "import": "ESM", "require": "CJS" },
  "./idl/vela_protocol.json": "./idl/vela_protocol.json"
}

Each subpath is independently importable. The browser subpath strips Node-only dependencies (helius-sdk, fs access) for use in Wallet Standard–compatible frontends.

PDAFactory: Centralized Derivation

The SDK centralizes all PDA derivation logic so consumers never hardcode seeds. Key derivations:

PDA	Seeds	Used By
Plan	`[b"plan", merchant, plan_id]`	Dashboard, checkout
Mandate	`[b"mandate", subscriber, plan]`	Widget, checkout, portal
Credential Mint	`[b"credential", mandate]`	Widget, checkout
PullApproval	`[b"pull-approval", mandate, epoch]`	Keeper, transfer hook
ProtocolConfig	`[b"protocol-config"]`	Admin
AgentMandate	`[b"agent-mandate", agent, authority]`	Agent billing

All seed constants and bump derivation live in src/constants.ts. Consumers import and call — never construct seeds manually.

Browser-Safe Barrel Export

The @vela/sdk/browser subpath provides:

All instruction builders
All account types and deserializers
PDA derivation
Event parsing
Constants and types

It excludes:

helius-sdk integration (Node-only RPC)
fs or path imports
Any server-side-only helpers

This allows the widget, checkout, and portal to use the SDK in browser contexts without bundling Node polyfills.

Event Schema Subpath

@vela/sdk/events exports typed event classes for every protocol event:

Event	When Fired	Parsed Fields
`PlanCreated`	Merchant creates a plan	merchant, planId, amount, frequency
`SubscriptionCreated`	User subscribes	subscriber, mandate, planId, credential
`PullExecuted`	Billing pull succeeds	mandate, amount, epoch, txSignature
`PullRejected`	Transfer hook rejects a pull	mandate, reason
`SubscriptionCancelled`	Mandate cancelled	subscriber, mandate
`AgentMandateCreated`	Agent budget mandate created	agent, authority, dailyLimit, totalCap

These types are used by vela-webhook for typed webhook processing and by vela-dashboard for real-time event display.

CLI Commands

bash

vela create-plan --name "Pro" --amount 9.99 --interval monthly
vela subscribe --plan <pubkey> --merchant <pubkey>
vela pull --mandate <pubkey> --amount 9.99
vela cancel --mandate <pubkey>
vela simulate --mandate <pubkey>           # Preflight: check without submitting
vela status --mandate <pubkey>             # On-chain state inspection
vela wrap --amount 100                     # Wrap SPL USDC → Token-2022
vela unwrap --amount 50                    # Unwrap Token-2022 → SPL
vela agent-mandate create --agent <pubkey> --daily-limit 50 --cap 500
vela stream start --recipient <pubkey> --rate 0.001 --cap 100

The CLI uses the SDK internally. Every command maps to an SDK method, making the CLI both a developer tool and a reference implementation.

SDK Stack ​

What It Is ​

Full SDK Architecture ​

Important Dependencies with Versions ​

All Consumers Inside the Workspace ​

Build + Package Shape ​

Package Exports Map ​

PDAFactory: Centralized Derivation ​

Browser-Safe Barrel Export ​

Event Schema Subpath ​

CLI Commands ​