> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velumx.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Concepts

# Core Concepts

Understanding the underlying mechanisms of the VelumX protocol.

## 1. Relayer-as-a-Service (RaaS)

VelumX is a **Relayer-as-a-Service** platform. The core value is the relayer infrastructure — not a set of protocol-specific contracts. Developers plug into VelumX via API key and call any Stacks contract they want, gaslessly.

The relayer:

* Co-signs sponsored transactions (adds the STX fee-payer signature)
* Manages STX balances per developer
* Handles nonce management and broadcast
* Enforces rate limits and spending caps per API key

## 2. Sponsored Transactions

Stacks has native support for **sponsored transactions**. In a sponsored transaction:

* `tx-sender` = the user (signs the transaction body, authorizes the action)
* `fee-payer` = the relayer (pays the STX network fee)

The user never needs STX. They sign the transaction with their existing Leather, Xverse, or OKX wallet. VelumX co-signs as the fee-payer and broadcasts.

## 3. Sponsorship Policies

### DEVELOPER\_SPONSORS

The developer's relayer pays STX gas. Users pay nothing at all. No paymaster contract needed.

**Best for**: Zero-friction onboarding, subsidized user experiences, any protocol action.

```
User signs tx → velumx.sponsor(txHex) → Relayer co-signs → Broadcast
```

### USER\_PAYS

The user pays a SIP-010 token fee (e.g. USDCx). The fee is collected atomically with the action via a **paymaster contract** that the developer deploys.

**Best for**: Sustainable fee models where users pay in the token they already hold.

```
User signs tx → velumx.sponsor(txHex) → Relayer co-signs → Broadcast
On-chain: paymaster collects fee → executes action (atomic)
```

## 4. The Paymaster Pattern

A paymaster is a Clarity contract that atomically:

1. Collects a SIP-010 fee from the user (`tx-sender`)
2. Executes a protocol action (swap, bridge, transfer, etc.)
3. Emits an event

The key property: if the protocol action fails, the entire transaction reverts — including the fee transfer. Users are never charged without their action executing.

**VelumX deploys one reference paymaster** (`velumx-defi-paymaster-v1`) for the VelumX DeFi frontend. Developers copy this as a template for their own integrations.

## 5. Deterministic Multi-Tenancy

Every developer gets their own isolated relayer address derived from a master key using HD path derivation.

* Funds are fully isolated per developer
* Analytics are accurate per tenant
* Revoking one API key doesn't affect others
* Developers can export their relayer private key from the Dashboard at any time

## 6. API Key as Security Gate

The API key is the only gate to the relayer. No on-chain whitelist, no registry contract. This means:

* Any Stacks contract call can be sponsored (the relayer doesn't inspect what contract is being called)
* Rate limits and spending caps are enforced server-side per API key
* Compromised keys can be revoked instantly from the Dashboard

## 7. Secure Proxy Pattern

Your `VELUMX_API_KEY` must never be exposed in client-side code. Use a server-side proxy that injects the key before forwarding requests to the VelumX API.

```
Browser → Your Backend Proxy (injects API key) → VelumX Relayer API
```