vela-protocol

Core Anchor workspace for the recurring billing primitive. Dual-program design: vela-protocol (main business logic) and vela-transfer-hook (transfer-time enforcement).

Purpose and Role

The on-chain billing primitive that every other repo depends on. It defines:

• Plan creation and management for merchants.
• Subscription mandates with scoped pull authorization.
• Streaming mandates with rate-per-second billing (v1.8).
• Agent mandates with scoped AI spending limits (v1.4).
• Pull approval flow: write ephemeral approval → transfer hook validates → transfer executes.
• Credential issuance (Non-Transferable Token-2022 tokens for subscribers).
• Protocol configuration (admin, keeper authority, token registry).
• Arcium MPC circuit integration (Phase 1+).

This repo is the root of truth for mandates, approvals, wrapped mint flows, credential issuance, billing events, and the transfer-hook enforcement boundary.

Tech Stack

Technology	Version	Purpose
Anchor	0.32.1	Program framework — IDL generation, account validation, CPI wrappers
Rust	1.89.0+	Language — required for stable IDL building
Solana CLI (Agave)	2.3.0+	Validator/deploy target
spl-token-2022	10.0.0	Token-2022 program crate — transfer hooks, fees, metadata
spl-transfer-hook-interface	0.10.0	Transfer hook interface — Execute instruction discriminator
spl-tlv-account-resolution	0.11.1	Extra account meta resolution for transfer hook
anchor-spl	0.32.1	SPL helpers for Anchor — Token-2022 constraints
LiteSVM (Rust)	latest	In-process VM for unit tests
LiteSVM (npm) + anchor-litesvm	0.6.0 / 0.2.1	TypeScript integration tests

Directory Structure

vela-protocol/
├── programs/
│   ├── vela-protocol/          # Main business logic program
│   │   ├── src/
│   │   │   ├── lib.rs          # Program entry, instruction dispatch
│   │   │   ├── state/          # Account structs (Plan, Mandate, StreamMandate, etc.)
│   │   │   ├── instructions/   # Instruction handlers
│   │   │   │   ├── create_plan.rs
│   │   │   │   ├── subscribe.rs
│   │   │   │   ├── execute_pull.rs
│   │   │   │   ├── execute_stream.rs      # v1.8
│   │   │   │   ├── initiate_upgrade.rs    # v1.8
│   │   │   │   ├── cancel.rs
│   │   │   │   ├── agent_mandate.rs       # v1.4
│   │   │   │   └── admin.rs               # Config, pause, keeper
│   │   │   └── errors.rs       # Error codes
│   │   └── Cargo.toml
│   └── vela-transfer-hook/     # Transfer enforcement program
│       ├── src/
│       │   ├── lib.rs          # Hook entry — discriminator-first dispatch
│       │   └── validate.rs     # Periodic vs streaming validation branches
│       └── Cargo.toml
├── encrypted-ixs/              # Arcium circuit definitions (Phase 1+)
├── tests/                      # TypeScript integration tests (LiteSVM)
├── target/                     # Build artifacts
├── Anchor.toml                 # Anchor workspace config
└── Cargo.toml                  # Workspace root

Deployment Target

• Devnet: Solana devnet (current — all testing and validation happens here).
• Mainnet: Planned post-v1.8. Deployment must follow the guarded ceremony in Protocol Deployment Runbook. Do not use raw anchor deploy as the normal release path.

Operations References

• Protocol Deployment Runbook
• Environment Registry
• Release Management
• Verification Matrix
• Repo Contracts

Dependencies

What It Depends On

Dependency	Type	Purpose
Solana Token-2022	Runtime	Transfer hook CPI, token operations
Arcium MXE	Runtime (Phase 1+)	Encrypted billing logic
Agave 2.3.0+	Runtime	Validator compatibility

What Depends on It

Consumer	How	What They Use
vela-sdk	Imports IDL	Instruction builders, account types, event definitions
vela-dashboard	Via SDK	Plan creation, subscriber management, keeper ops
vela-checkout	Via SDK	Subscription transaction building
vela-portal	Via SDK	Mandate cancellation, plan switching
vela-widget	Via SDK	Checkout transaction building
vela-webhook	Via SDK events	Zod-typed event schemas from program events
vela-synthetic	Via SDK	E2E validation against deployed program

Current Status

• v1.8 complete: All three phases (streaming, upgrades, multi-token) shipped.
• 8 milestones: v1.0 through v1.8 — 47 phases, 206+ plans.
• 9 instruction groups: Periodic, Streaming, Upgrades, Agent, Admin, Config, TokenConfig, Credential, Stream.
• 12 data account types: ProtocolConfig, KeeperConfig, VelaPlan, UsagePlan, VelaMandate, StreamMandate, AgentMandate, PullApproval, MerchantState, TokenConfig, BillingEvent, UsageReport. Credentials are Token-2022 mints with the Non-Transferable extension (not data accounts).

Notable Design Decisions

Dual-Program Split

The transfer hook (vela-transfer-hook) is a separate program from the main protocol (vela-protocol). This is because the hook runs synchronously during transfer_checked CPI — it must be minimal, auditable, and fail-closed. Any bug either lets merchants steal or blocks legitimate payments.

Upgradeable Hook with Dynamic ExtraAccountMetaList

8 reserved slots in the ExtraAccountMetaList allow the hook to add new account dependencies (e.g., StreamMandate in v1.8) without redeploying the protocol.

Fail-Closed Security

The transfer hook fails closed on every validation path:

• Unknown discriminators → WrongAccountType error.
• Missing approvals → ApprovalNotFound error.
• Expired approvals → ApprovalExpired error.
• Insufficient balance → typed error, no silent overdraft.

Settle-Then-Mutate Invariant (v1.8)

Every stream mandate mutation (pause, resume, rate change, cancel) settles accrued debt first. A single private helper enforces this across all mutation paths.

Checked Math

All settlement calculations use checked_* operations with u128 intermediates to prevent overflow near u64::MAX boundaries.

This Repo is Unusual

It's not just an Anchor program — it also owns the privacy-compute interface (Arcium circuits in encrypted-ixs/) and their generated artifacts. Protocol delivery spans both Rust program code and Arcium circuit outputs.