Helius

Helius is the primary chain-facing service layer across the workspace. It provides RPC access, webhook event indexing, and DAS API integration.

---

Where Helius Shows Up

Surface	Helius Role	Dependency
vela-sdk	Optional enhanced RPC path, webhook helpers	Optional peer dependency (helius-sdk ^2.2.2)
vela-dashboard	Protocol reads, webhook ingestion, indexed merchant-facing state	Direct dependency
vela-webhook	Webhook source for billing and subscription event indexing	Direct dependency
Planning + audits	Source of webhook/data-integrity concerns for v1.2 findings	Referenced in .planning/

---

Functional Roles

1. RPC Provider

Helius provides enhanced Solana RPC access with:

• Dedicated endpoints — no rate-limiting at the free tier for API-key holders
• Enhanced transactions API — parsed transaction data with human-readable labels
• getAccountInfo with parsed JSON — used for mandate and plan state reads in the dashboard
• Connection pooling — SDK handles connection reuse

The SDK treats Helius as an optional enhanced RPC. Core functionality works with any Solana RPC endpoint. With Helius, you get webhook helpers and DAS API as additional capabilities.

2. Webhook Event Indexing

This is Helius's most critical role in VelaPay. The merchant and admin experiences depend on reliable webhook delivery for real-time state updates.

Webhook Configuration

Setting	Value
Webhook type	Enhanced (parsed transaction data) or Raw (lower latency)
Addresses	Vela program ID + mandate PDAs
Transaction types	Custom program events (mandate creation, pull execution, cancellation)
Capacity	Up to 100,000 addresses per webhook

Events VelaPay Indexes

On-chain Event	What Triggers It	Dashboard Effect
PlanCreated	Merchant creates a plan	New plan appears in dashboard
SubscriptionCreated	User subscribes via checkout or widget	New subscriber added to list
PullExecuted	Billing pull succeeds	Revenue updated, subscriber state refreshed
PullRejected	Transfer hook rejects a pull	Failed payment flagged, grace period starts
SubscriptionCancelled	Mandate cancelled	Subscriber status updated

Processing Pipeline

Helius webhook → vela-webhook Worker → Queue → Dashboard consumer
                                                     ↓
                                              D1 billing_events table (idempotent)
                                                     ↓
                                              Subscriber snapshots updated
                                                     ↓
                                              Invoice auto-generation (if pull_executed)

The webhook worker processes events idempotently — duplicate webhook deliveries are deduplicated using the transaction signature + event type as a unique key.

3. DAS API (Digital Asset Standard)

Helius's DAS API provides compressed NFT and token metadata queries. VelaPay uses it for:

• Vela Credential lookups — query subscriber credentials across merchants
• Metadata resolution — fetch plan metadata from Token-2022 Metadata Pointer extension
• Asset verification — confirm credential NFT ownership for token-gating

---

Why Helius Matters

The product is not just on-chain logic plus frontends. The merchant and admin experiences depend on the reliability of the Helius-powered indexing path. If webhooks are delayed or dropped:

• Merchants don't see new subscribers in real-time
• Revenue analytics are stale
• Failed payments aren't flagged promptly
• Invoice generation is delayed

This is why the planning layer repeatedly references webhook coverage and sync behavior. The webhook pipeline is a critical production dependency, not an optional enhancement.

---

Integration Patterns

In the SDK

// Optional Helius-enhanced RPC path
import { Helius } from 'helius-sdk';

const helius = new Helius('api-key');
const connection = helius.rpc; // Drop-in Connection replacement

The SDK uses helius-sdk as an optional peer dependency. Without it, the SDK falls back to standard @solana/web3.js Connection.

In the Dashboard

// Webhook handler processes Helius events
app.post('/api/webhooks/helius', async (c) => {
  const events = await c.req.json();
  for (const event of events) {
    await processBillingEvent(event); // Idempotent
  }
  return c.json({ ok: true });
});

The dashboard exposes a webhook endpoint that Helius calls on every relevant on-chain event.

In the Webhook Worker

The vela-webhook Worker is the dedicated ingestion point:

• Receives Helius webhooks
• Validates event signatures and payloads
• Deduplicates using tx signature + event type
• Pushes to Cloudflare Queue for async processing
• Dashboard worker consumes from queue and updates D1

This separation ensures webhook ingestion is decoupled from dashboard state updates — if D1 is slow, webhooks don't back up.

---

Webhook Reliability Considerations

What Can Go Wrong

Failure Mode	Impact	Mitigation
Webhook delivery delayed	Stale dashboard state	Queue-based processing, eventual consistency
Webhook dropped	Missing billing event	Reconciliation cron (checks on-chain state vs D1)
Duplicate delivery	Double-processed event	Idempotency key (tx signature + event type)
Out-of-order delivery	State inconsistency	Event timestamp ordering, conflict resolution
Helius API downtime	No new events indexed	Dashboard reads from D1 (cached state), catch-up when Helius recovers

Reconciliation Strategy

The planning layer references a reconciliation cron that periodically checks:

1. On-chain mandate state vs. D1 subscriber snapshots
2. Expected billing events (based on schedule) vs. received webhooks
3. Missing invoices for confirmed pull_executed events

This reconciliation is the safety net for the indexing pipeline. It runs every 6 hours and creates missing records for any events that were dropped.

---

Helius SDK Version Notes

• helius-sdk 2.2.x uses @solana/kit 3.0.x internally
• This does not conflict with @solana/web3.js v1 used by the Anchor client
• The SDK exposes a clean API that doesn't leak Kit types into your code
• Helius SDK works on Bun (important for the workspace's package manager constraint)