Vela Labs Internal Wiki

Appearance

Root Research Docs ​

The workspace root contains ten markdown documents that collectively shaped VelaPay's product story, positioning, and execution logic. They were written between March 28 and April 13, 2026 — a compressed research-to-architecture sprint that produced the intellectual foundation for the entire project.

This page summarizes each document's content, key insights, influence on the project, and current accuracy.

01-vela-labs-brand.md ​

What It Covers ​

Company, protocol, and product naming architecture. Domain strategy. How to talk about the project.

Key Insights ​

  • Three-layer naming: Vela Labs (company) → Vela Protocol (primitive) → VelaPay (product)
  • The name "Vela" has dual meaning: Latin velum (veil/sail) — veils billing data, sails payments forward. Also a southern sky constellation, fitting Solana's astronomy references.
  • Primitives don't have product names. Token-2022 isn't "TokenPay." Squads isn't "SquadsMultisig." Vela is the recurring value transfer primitive.
  • Domain strategy: velapay.com (primary), docs.velapay.com, app.velapay.com, velalabs.xyz (redirect)

How It Influenced the Project ​

Established the naming convention used across all repos, docs, and the landing page. The "protocol vs. product" distinction became the organizing principle for the entire workspace structure.

Current Accuracy ​

Still accurate and authoritative. No naming changes since this was written.

02-privacy-first-subscription-billing-deep-dive.md ​

What It Covers ​

The original market thesis and technical architecture. Competitive landscape (10 failed subscription projects in Colosseum corpus). Transfer hook mandate design. Revenue model. Go-to-market strategy.

Key Insights ​

  • The gap: On-chain businesses have no native way to charge recurring payments. Existing approaches require unlimited token approvals or centralized scheduling.
  • 10 teams tried subscription billing on Solana across Colosseum hackathons. None won prizes. None made accelerator. None used Token Extensions or Arcium.
  • Transfer hook as billing engine: Merchant registers plan → user approves mandate → transfer hook validates every pull → Arcium encrypts billing logic.
  • Revenue model: 1-2% transaction fee on payment volume. SaaS dashboard tiers ($49-499/mo). SDK licensing. Yield share on escrow.
  • GTM sequence: Crypto-native SaaS → Web3 creator economy → Traditional SaaS accepting crypto → Agent-to-agent commerce.
  • Moat analysis: SDK lock-in, data network effects, privacy moat (Arcium), standard-setting, composability advantage.
  • Market signals: a16z naming monthly billing as a core stablecoin unlock. Stripe acquired Bridge for $1.1B. Stablecoin volume 3× Visa.

How It Influenced the Project ​

This is the founding document. Every architectural decision traces back to insights here. The transfer hook mandate design, four-layer architecture (Protocol → Billing Engine → Revenue Finance → Applications), and Arcium integration strategy all originated in this doc.

Current Accuracy ​

Directionally correct but partially superseded:

  • Revenue model refined in later docs (08) — the lending margin is now understood as the sleeper revenue stream, not transaction fees alone
  • GTM reframed in 05 and 08 — agent-first rather than merchant-first is now the preferred opening
  • Technical architecture evolved significantly — the two-phase Arcium billing pattern (documented in 06/07) wasn't designed here
  • The competitor analysis (10 projects) was expanded with code-level teardowns in 06

03-alternative-angles-privacy-subscription-billing.md ​

What It Covers ​

Seven alternative angles that challenge, expand, or reframe the original thesis. Each angle is a contrarian take backed by evidence.

Key Insights ​

  1. Streaming vs. pull-based: Monthly billing is a legacy construct. Per-second streaming on sub-second finality blockchains is the natural model. Hybrid billing engine that supports both.
  2. Agent-first, not merchant-first: AI agents are the bigger near-term customer. x402-compatible mandates with cryptographically enforced spending limits.
  3. Subscription revenue as DeFi collateral: MRR attestations via Arcium unlock revenue-backed lending — the Pipe.com of crypto.
  4. Tradeable subscriptions: Vela Credentials as financial instruments. Secondary market for unused subscription time.
  5. Why previous attempts failed: Approval problem (unlimited spending), no keeper network, wrong customer segment, no distribution, built features not protocols.
  6. Privacy as regulatory compliance: GDPR may require encrypted billing. Arcium isn't a nice-to-have — it's legally required for EU customers.
  7. Wallet dependency risk: Wallets control mandate approval UX. If Phantom doesn't render mandates clearly, users won't understand what they're signing. Solution: own the checkout flow with the widget.

How It Influenced the Project ​

  • Streaming became a planned billing mode (stream engine in Phase 3 of the roadmap)
  • Agent-first became the dominant narrative for hackathon positioning (05, 06, 07)
  • Revenue as collateral became Layer 3 of the architecture (MRR Oracle + lending)
  • Widget strategy directly shaped vela-widget's split architecture (loader + iframe with wallet relay)
  • Failure pattern analysis informed what NOT to build (no vault escrow, no off-chain triggers, no unlimited approvals)

Current Accuracy ​

Still highly relevant. The agent-first angle proved especially prescient — MCPay won 1st Stablecoins at Cypherpunk, validating the agent payment narrative. The streaming angle is built but not yet the primary billing mode.

04-product-blueprint-and-roadmap.md ​

What It Covers ​

The complete product architecture, technical design, and phased roadmap. Converts the thesis from 02 into concrete requirements.

Key Insights ​

  • Four-layer architecture: Protocol Core + Privacy (Layer 1) → Billing Engine (Layer 2) → Revenue Finance (Layer 3) → Applications (Layer 4)
  • Why Arcium, not Confidential Balances: CB encrypts token amounts only. Arcium runs arbitrary computation on encrypted data — usage patterns, pricing logic, subscriber counts, churn rates. For billing, the business intelligence around the payment matters more than the payment amount itself.
  • Billing modes: Fixed Pull, Streaming, Usage-Based, Hybrid — all routing through Arcium.
  • Phased roadmap: Phase 0 (Foundation, weeks 1-4) → Phase 1 (Arcium Privacy, weeks 5-12) → Phase 2 (Agent Economy, weeks 13-20) → Phase 3 (Revenue Finance, weeks 21-32) → Phase 4 (Superapp, weeks 33-52)
  • Flywheel: More merchants → more subscribers → more data in Arcium → better analytics → DeFi capital → cheaper financing → more merchants.
  • Revenue trajectory: $0 (Phase 0-1) → $50-200K (Phase 1-2) → $200K-1M (Phase 2-3) → $3-10M+ (Phase 4+).

How It Influenced the Project ​

This is the architectural blueprint. The four-layer architecture is the organizing principle for the entire workspace:

  • Layer 1 → vela-protocol + Arcium integration
  • Layer 2 → Keeper automation, billing engine (distributed across workers)
  • Layer 3 → Planned future (MRR Oracle, lending, marketplace — documented in 10-future-vision-layer3-and-beyond.md)
  • Layer 4 → vela-dashboard, vela-widget, vela-checkout, vela-portal

Current Accuracy ​

The architecture is still the canonical reference. The roadmap phases have been renumbered and expanded in the planning layer (.planning/ has 48+ phases now, not 4). The revenue estimates remain speculative. The "Why Arcium over CB" analysis is still correct and frequently cited.

05-pm-strategy-and-hackathon-brief.md ​

What It Covers ​

Product manager's lens on making VelaPay world-class. Ideal Customer Profile refinement. Two-products-must-be-great framework (merchant SDK + subscriber UX). Colosseum Frontier hackathon brief with track recommendations.

Key Insights ​

  • ICP tiers: Tier 1 (now) = on-chain data/RPC/analytics SaaS. Tier 2 (next) = DePIN networks. Tier 3 (later) = AI agent frameworks.
  • Two products: Merchant SDK + Dashboard AND Subscriber UX / Mandate Approval Flow. Every competitor built only the merchant side. The subscriber UX column is empty across the entire competitive field.
  • Agent narrative unlock: VelaPay's mandate system is the ideal AI agent payment primitive. x402 is per-request; Vela mandates are ongoing, scoped, enforced.
  • Primitive positioning trap: Don't declare the primitive before earning it. Ship product → get merchants → prove value → other protocols build on top → declare primitive. Not the reverse.
  • Colosseum track recommendation: Primary: Stablecoins. Secondary: Infrastructure. Optional: AI.
  • Hackathon timing: Frontier hackathon April 6 – May 11, 2026. Pre-existing work explicitly allowed.

How It Influenced the Project ​

  • ICP tiers shaped the design partner outreach strategy
  • The subscriber UX emphasis directly drove investment in vela-checkout and vela-portal
  • Track recommendations guided the hackathon submission strategy
  • The "primitive positioning trap" insight prevented premature protocol declarations

Current Accuracy ​

The ICP analysis is still directionally correct but the agent narrative has grown even stronger since writing. The hackathon dates are past (Frontier ran April–May 2026). The competitive analysis in 06 supersedes some of the competitor mentions here.

06-colosseum-competitive-research.md ​

What It Covers ​

Deep competitive analysis from 5,400+ Colosseum builder projects. Code-level teardowns of every relevant competitor. What Colosseum judges actually evaluate. Hardened winning strategy with narrative positioning.

Key Insights ​

  • What Colosseum judges evaluate (from co-founders' blog posts): Execution over novelty. Demo over everything. Solana integration depth. Real users. Founder potential.
  • Pre-existing work is explicitly allowed: Proven by Unruggable (4 consecutive hackathons, HM→HM→3rd→Grand Prize $30K).
  • Deep teardowns:
    • Subly: Arcium budget check hardcoded to true. Routes payments through PayPal. Consumer yield wrapper, not billing infrastructure.
    • Aeon Protocol: Vault escrow (bad capital efficiency), no Token-2022, no privacy, no SDK.
    • Bundl: NestJS + MongoDB SaaS with thin on-chain component. Backend cron pulls. If backend dies, payments stop.
    • MCPay (1st Stablecoins $25K + C4 Accelerator): x402 for MCP tools. Pay-per-call, no spending caps.
    • Latinum (1st AI $25K): MCP-compatible wallet. Budget in Nuxt server code — no protocol enforcement.
    • DePlan (5th Consumer $5K): Pay-as-you-go. No spending caps, no privacy, no transfer hooks.
  • What Vela has that no one else does: Transfer hook mandate enforcement (zero projects in 5,400+ use this for billing), two-phase Arcium billing, fail-closed privacy, full stack shipping (protocol + SDK + CLI + dashboard + landing + docs + privacy layer).
  • Positioning against each competitor: Pre-written judge FAQ answers.

How It Influenced the Project ​

This document shaped the entire hackathon submission strategy (expanded in 07). The competitor teardowns directly influenced feature prioritization — agent mandates, transfer hook enforcement, and subscriber UX were all validated as differentiators by the absence of any competitor doing them.

Current Accuracy ​

The competitor analysis is timeless — those projects haven't meaningfully evolved. The Colosseum judging criteria remain valid across hackathons. The positioning language is still used in pitch materials.

07-winning-strategy.md ​

What It Covers ​

Detailed 5-week build plan for the Colosseum Frontier hackathon. What to build during the hackathon window. Pitch video script. Technical demo sequence. Umbra integration assessment. Post-Colosseum growth path.

Key Insights ​

  • What's already shipped (pre-hackathon): 15 phases, v1.0 + v1.1 (Arcium). Protocol, SDK, CLI, dashboard, landing, docs, transfer hooks, Arcium integration, keeper, checkout widget, analytics, gap closures.
  • 5-week build plan: Week 1 (Agent Mandates) → Week 2 (Umbra + x402) → Week 3 (Subscriber Portal + Stream Engine) → Week 4 (Pitch + Demo + Hardening) → Week 5 (Polish + Submit)
  • The money shot: Transfer hook rejecting a $99.99 pull on a $9.99 mandate — the validator itself refusing the transfer.
  • Three narratives for three tracks: Infrastructure ("billing primitive"), Stablecoins ("protocol-level spending enforcement"), AI ("agent allowances, not blank checks")
  • Umbra assessment: Can't hide individual pull amounts (hook must see amount for validation). But adds balance privacy (merchant aggregate revenue, subscriber total holdings). Three-layer privacy story: transfer hooks + Arcium + Umbra.
  • Demo paradox: Hiding amounts hurts the hackathon demo. The $9.99-passed/$99.99-blocked moment needs visible amounts.
  • Post-Colosseum: Vertical domination → Agent economy → Web2 bridge → Revenue finance → Amount privacy.

How It Influenced the Project ​

This document drove the hackathon execution. The agent mandate feature was built. The subscriber portal became vela-portal. The pitch video structure was followed. The Umbra assessment's honest finding (can't hide individual pull amounts in the hook) is now accepted architectural truth.

Current Accuracy ​

The hackathon is past. The 5-week plan was executed (partially). The Umbra assessment's architectural constraints are still valid. The post-Colosseum growth path is still the team's reference for sequencing. The pitch video structure is reusable for future demo contexts.

08-vela-value.md ​

What It Covers ​

Research-backed analysis of Vela's core value proposition. Honest constraints. Product recommendations for Phase 1. Grounded in 1,997 Colosseum projects sampled.

Key Insights ​

  • Szabo's vision: Vela's transfer hook mandate is the first implementation of Nick Szabo's 1994 smart contract definition applied to recurring payments — the agreed terms are executed by the chain, not enforced by a trusted intermediary after the fact.
  • Every competitor is an allowance wrapper: User delegates token allowance → relayer pulls on schedule → if relayer misbehaves, blockchain doesn't stop it. Vela's mandate runs inside the Token-2022 program on every transfer.
  • Token-2022 production readiness: Orca integrated TransferHook in May 2024. If the largest Solana DEX trusts it, it's no longer experimental.
  • USDC constraint: Circle's USDC on Solana is SPL, not Token-2022. Vela's mandate enforcement requires a Token-2022 mint, hence the wrapped USDC approach. Early adopters should target protocols already issuing Token-2022 tokens (PYUSD, USDY).
  • The Latinum distinction: Latinum (1st AI) manages budgets in a Nuxt server. Vela manages budgets in a transfer hook. A compromised agent cannot exceed its Vela mandate. A Latinum budget can be drained by any agent with wallet access.
  • Honest constraints: Privacy is not live in Phase 0. A real merchant is required for the demo to land. GTM is the hardest problem, not the protocol.
  • Product recommendations: Lead with agent budget mandates, add usage metering, privacy as design partner pitch, SDK-first distribution.

How It Influenced the Project ​

  • The "Szabo's smart contract" framing became the canonical value statement
  • The wrapped USDC strategy was validated and documented
  • The honest constraints section prevented overpromising in pitch materials
  • Product recommendations shaped the agent mandate and usage metering features

Current Accuracy ​

Still the most accurate statement of Vela's differentiated value. The USDC constraint analysis is correct. The Latinum distinction is frequently cited in competitive positioning. The honest constraints remain honest — privacy is now live (v1.1) but the "real merchant" and GTM challenges persist.

09-hosted-checkout-billing-plan.md ​

What It Covers ​

Detailed plan for v1.5: hosted checkout, invoicing, customer portal, pricing table. Fills the biggest UX gap in crypto billing.

Key Insights ​

  • The gap: No crypto billing solution answers "where's my invoice?", "how do I cancel?", or "can I upgrade my plan?"
  • Competitive table: VelaPay is the only solution with hosted checkout + invoicing + customer portal + pricing table + private billing data + on-chain enforcement.
  • New repos: vela-checkout (standalone Worker at pay.velapay.com), vela-portal (standalone Worker at portal.velapay.com).
  • Security: Turnstile, rate limiting, open redirect prevention, abuse reporting, merchant verification.
  • Invoice lifecycle: draft → open → paid → void. Auto-generation from webhook events. PDF via pdf-lib. Email delivery via Resend.
  • Customer portal auth: SIWS standard with domain binding. Magic link fallback. Multi-wallet linking.
  • Pricing table: <vela-pricing-table> web component. Shadow DOM for style encapsulation. WCAG 2.1 AA accessibility.

How It Influenced the Project ​

This became the v1.5 implementation plan. vela-checkout and vela-portal were created as separate repos following this document's architecture. The service binding pattern (checkout → dashboard, portal → dashboard) was designed here.

Current Accuracy ​

Partially implemented. vela-checkout exists as a repo with wrangler.toml and service bindings. vela-portal exists with SIWS auth. Invoice generation, PDF delivery, and pricing table are in various stages of implementation. The architecture decisions are being followed.

10-future-vision-layer3-and-beyond.md ​

What It Covers ​

Long-horizon features that complete VelaPay's 4-layer architecture. Beyond the current development cycle (v1.0–v1.7). None in active development.

Key Insights ​

  • MRR Oracle: On-chain oracle publishing verifiable MRR from mandate state. No traditional oracle can provide this. Enables DeFi composability (lending against verified revenue).
  • Revenue-Backed Lending: Merchants borrow against proven recurring revenue. Repayment via mandate intercept (transfer hook routes a percentage to lending pool). Liquidation = revenue assignment, not token auctions.
  • Subscription Marketplace: Tradeable credentials. Corporate seat management, resale market, gifting. Royalties via Token-2022 Transfer Fee. Mandate rebinding on transfer.
  • Protocol Governance: Phase A — Squads multisig (near-term). Phase B — Token governance (long-term). Parameter categories with different quorum requirements.
  • Confidential Balances: Token-2022 Confidential Transfer extension for encrypted transfer amounts. Adds end-to-end privacy alongside Arcium. Wait for Solana runtime maturity.
  • Priority sequencing: Governance (Squads) → MRR Oracle → Marketplace → Lending → Confidential Balances.

How It Influenced the Project ​

This document exists to prevent scope creep. It captures the long-term vision so the current development cycle stays focused on Layers 1-2 and the core application surfaces. When planning future milestones, this document serves as the reference for what comes after the billing primitive is proven.

Current Accuracy ​

These are long-term plans, not commitments. The sequencing is logical but may change based on adoption patterns. Confidential Balances remains blocked on Solana runtime maturity. The MRR Oracle is the highest-value future feature but requires sufficient mandate volume.

Themes Repeated Across the Set ​

Several ideas surface repeatedly across all ten documents:

  1. Transfer-hook mandates are the core primitive. Every doc returns to this: the billing enforcement lives inside the token transfer itself. This is the one thing no competitor has.

  2. Privacy matters because public billing data is a business leak. Not because privacy is cool, but because competitors, investors, and chain analysts can see your subscriber count, revenue, churn, and pricing. Arcium encrypts the business intelligence.

  3. Recurring billing on Solana is still open territory. 10 teams tried, 0 won, 0 made accelerator. The design space is wide open.

  4. The best near-term wedge may be agent budgets, not generic subscriptions. The agent economy narrative is the strongest hook for hackathon judges and early adopters.

  5. Distribution and UX are as important as protocol design. Shipping a protocol nobody uses is the #1 failure mode. The subscriber UX, checkout flow, and developer experience are product surfaces, not afterthoughts.

  6. Ship the product first, declare the primitive when 10 merchants use it. The "primitive positioning trap" — don't announce yourself as the standard before earning it.

  7. Every competitor is an allowance wrapper. The structural difference between "I promise not to overcharge" and "the blockchain physically prevents overcharging" is the pitch.

Current Read on the Set ​

The research docs remain directionally aligned with the codebase and planning artifacts, but the workspace has moved past some older assumptions:

What's ChangedFromTo
Repo count5 repos in early docs11 repos (protocol, sdk, dashboard, admin, web, docs, widget, checkout, portal, webhook, synthetic)
Admin ops layerConceptualReal and shipped (vela-admin)
WidgetConceptualReal and shipped (vela-widget with split architecture)
Hosted checkoutNot plannedPlanned in 09, partially implemented (vela-checkout)
Customer portalNot plannedPlanned in 09, partially implemented (vela-portal)
Arcium privacyPhase 1 futureShipped in v1.1 (two-phase billing, fail-closed)
Phase numbering4 phases in 0448+ phases in .planning/
GTM emphasisMerchant-firstAgent-first (stronger narrative signal)
Umbra integrationProposed in 07Assessed as architecturally limited for amount privacy; balance privacy still valuable

The planning layer (.planning/) now contains more current operational truth than these root documents. The root docs should be read as the intellectual foundation, with .planning/ as the current execution state.

Internal knowledge base for the Vela Labs workspace.

Grounded in .planning/, root research docs, repo manifests, and milestone artifacts.