Appearance
Glossary
Domain vocabulary used across the VelaPay codebase. Terms are grouped: protocol concepts, billing modes, infrastructure roles, operational terms.
When adding a term, link the authoritative source file in the repo so future readers can verify the definition against the code.
Protocol Concepts
Mandate
A subscriber's authorization to be charged according to a specific plan. Lives on-chain as a Mandate PDA. Carries the period bounds, pull count, pending upgrade state, and version. Cancellation revokes it. Source: vela-protocol/programs/vela-protocol/src/state/mandate.rs.
Plan
A merchant's billing plan definition: amount, period, mint, version. The shape that mandates reference. Many subscribers can share one plan. Source: vela-protocol/programs/vela-protocol/src/state/plan.rs.
Credential
A non-transferable Token-2022 token minted to a subscriber as proof of an active subscription relationship. Per-merchant since v1.7 — the credential tracks subscriber↔merchant, not subscriber↔plan, so plan switching doesn't require re-minting. Source: vela-protocol/programs/vela-protocol/src/state/credential.rs.
Pull
The act of charging a subscriber. The merchant or a keeper invokes execute_pull, which writes a PullApproval and immediately follows with a Token-2022 transfer_checked whose hook validates the approval.
PullApproval
An ephemeral PDA that authorizes one Token-2022 transfer up to a specific amount before a specific time. Created by execute_pull and consumed (validated and effectively cleared) by the transfer hook in the same transaction. The bridge between billing logic and transfer enforcement.
StreamMandate
A rate-per-second billing authorization. Distinct from Mandate — not "periodic with period=1s". Carries authorized_max_rate, last_settled_ts, total_streamed, paused, pending_rate_change. Settled via execute_stream with the settle-then-mutate invariant.
AgentMandate
A scoped budget for an AI agent: daily limit, lifetime cap, per-service limit, pull cooldown. Lets an agent autonomously charge within bounds the human approved.
Transfer Hook
Custom program that runs synchronously inside every Token-2022 transfer_checked. The fail-closed enforcement layer for VelaPay: validates that the active mandate, approval, and constraints are all satisfied. Lives in the separate vela-transfer-hook program for security isolation.
Token-2022
The token program used by VelaPay (never legacy SPL Token). Provides Transfer Hooks, Transfer Fees, Metadata Pointer, Non-Transferable, and Interest-Bearing extensions — all of which VelaPay relies on.
MXE (Multiparty Computation eXecution Environment)
The Arcium primitive that runs computation on encrypted data. VelaPay uses MXE for billing-logic validation, usage metering, and aggregate analytics — none of which are visible to validators or chain analysts.
Circuit
A program that runs inside an MXE. VelaPay's circuits validate mandate constraints on encrypted inputs and emit encrypted outputs that only authorized parties can decrypt.
TokenConfig
Per-mint billing rail configuration: decimals, enabled, oracle. Introduced in v1.7 so the protocol supports multiple stablecoins (USDC, PYUSD, …) with consistent rendering and routing logic.
ProtocolConfig
Global protocol configuration: admin, transfer hook program ID, keeper authority, paused state. Single PDA per network. Updated only by admin instructions.
Billing Modes
Periodic
Fixed amount charged on a fixed cadence (every 30 days, every billing period). The classic subscription model. Backed by Mandate + execute_pull.
Streaming
Continuous accrual at a maximum rate-per-second. Settled via execute_stream. Backed by StreamMandate. Useful for cloud usage, AI inference billing, or per-second SaaS plans.
Usage-based
Bill on consumed metrics that flow through Arcium MXE encrypted compute. Merchants charge on private metrics without exposing them to chain observers.
Agent budget
Bounded autonomous spending by AI agents. Backed by AgentMandate. Distinct from periodic and streaming because the agent decides when to pull within the cap.
Wrap-and-subscribe
A convenience flow that wraps native USDC into VelaPay's billing rail and creates a mandate in one transaction. Source: vela-sdk/src/instructions/wrap-and-subscribe.ts.
Infrastructure & Workflow
Keeper
A Cloudflare Worker authorized via ProtocolConfig.keeper_authority that executes scheduled pulls or stream settlements on behalf of merchants. Multiple keepers exist with different cadences and failure semantics. See Keeper Operations →.
Settle-then-mutate
The rule for all stream-state mutations: settle accrued debt before mutating state (pause, resume, change rate, cancel). Enforced by a single private helper that every mutation path calls.
Fixture
A pre-built test asset (signed payload, deterministic account state) used by integration and smoke tests. The webhook fixture set lives in vela-webhook/test-fixtures/.
Backfill
Reconciling D1 state with on-chain truth when a webhook delivery is missed. Reads vela-protocol accounts directly and re-creates missed billing events. See Webhook Troubleshooting →.
Fan-out
The dashboard worker's pattern of taking one inbound Helius event and dispatching multiple outbound deliveries (merchant webhook, dashboard UI update, snapshot mutation, email).
DLQ (Dead Letter Queue)
Where webhook deliveries land after exhausting their retry schedule. Surfaced in the admin console for manual replay or merchant outreach.
Idempotency Key
A deterministic key derived from the on-chain event that lets consumers dedup inbound deliveries and replay safely. Source: vela-webhook/src/idempotency.ts.
Synthetic
A scripted, scheduled exercise of the billing pipeline by vela-synthetic against devnet staging. The first signal that something is broken end-to-end.
Smoke (mail)
A throwaway worker (vela-mail-smoke) that drives every transactional email template against the real CF Email Service before each release.
Operational Terms
Phase
A unit of planned work in .planning/phases/. Numbered integers for planned phases (1, 2, 3, …) and decimals for urgent insertions (72.1).
Milestone
A grouping of phases under a version label (v1.0–v1.8). See Milestone History →.
Devnet staging
The deployed devnet environment that the synthetic worker, demo, and smoke tests run against. Acts as production-shaped infrastructure without real money at stake.
Upgrade authority
The Solana account allowed to upgrade a deployed program. For VelaPay devnet today: EkyMDqChwLDyx8XUxEFB7Ngvk9Yfp2DGEJ6VzqqbgErD. Mainnet authority is generated and frozen during the deployment ceremony.
Service binding
Cloudflare's pattern for one Worker calling another via internal RPC instead of public HTTP. Used between vela-admin and the vela-dashboard Worker so admin traffic never hits merchant-facing endpoints.
Pause / unpause (protocol)
Admin instructions that flip ProtocolConfig.paused. While paused, pulls and stream settlements fail closed; cancellations and reads still work. See Incident Response →.