Skip to main content

​
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