Getting StartedCore Concepts

Core Concepts

Understanding the key concepts in Veil.

Vaults

A vault is a token account that holds funds for payment schedules. Each employer wallet can have one vault per token mint.

Properties:

  • holds a single SPL token mint
  • must use a mint allowed by the protocol whitelist when whitelist mode is enabled
  • tracks available vs reserved balance
  • is controlled by the employer wallet through the program

Lifecycle:

  1. create vault with initVault()
  2. deposit tokens with deposit()
  3. reserve funds when schedules are created
  4. withdraw available balance with withdraw()

Schedules

A schedule defines a recurring payout plan with hidden recipients.

Key fields:

  • intervalSecs - time between executions
  • reservedAmount - total funds reserved
  • perExecutionAmount - amount paid per cycle
  • merkleRoot - root of the recipient Merkle tree
  • totalRecipients - number of recipients
  • nextExecution - unix timestamp of the next run

scheduleId is used to derive the schedule PDA, but it is not stored as a field inside the on-chain ScheduleAccount.

Status values:

  • Active
  • Paused
  • Cancelled

Merkle Trees

Merkle trees let Veil verify membership without storing the full recipient list on-chain.

Structure

        Root (stored on-chain)
       /              \
    Hash(0-1)      Hash(2-3)
    /      \        /      \
  Leaf0  Leaf1  Leaf2    Leaf3

Each leaf is hash(recipient_address || amount).

Why Merkle Trees?

  • privacy - only the root is committed on-chain
  • verification - proofs confirm membership without revealing the full set
  • efficiency - proof size grows logarithmically with recipient count

Building a Tree

import { buildMerkleTree } from "@veil-dev/sdk";
 
const recipients = [
  { address: pubkey1, amount: 100_000n },
  { address: pubkey2, amount: 200_000n },
];
 
const { root, proofs } = buildMerkleTree(recipients);

Batch Execution

Payments execute in batches:

  1. batch start - first successful claim sets batchStartTime
  2. claims - recipients are processed with Merkle proofs
  3. completion - all recipients are paid or timeout is reached
  4. settlement - reserved amount is decremented and the next run is scheduled

The global batch timeout is configurable in VeilConfig and defaults to 7 days in the SDK helper.

Ephemeral Rollups

MagicBlock ER provides:

  • TEE execution
  • private claim flow
  • state handoff back to Solana through commit

Coordinator

The coordinator automates execution and stores off-chain payout metadata:

  • monitors schedules for execution time
  • validates and stores recipient payloads
  • delegates to ER
  • executes claims
  • commits final state
  • records execution history

Requirements:

  • PostgreSQL
  • Redis (recommended for distributed rate limiting)
  • ER authority keypair
  • Solana RPC connection

Reserved vs Available

Available - funds that can be withdrawn or used for new schedules

Reserved - funds locked for active schedules

Total Balance = Available + Reserved

When a schedule is created, funds move from available to reserved. When a schedule completes or is cancelled, funds are released back to available.

Dashboard Conveniences

The published employer dashboard adds workflow features on top of the protocol and SDK:

  • CSV / Excel recipient imports
  • local saved schedule templates per wallet
  • coordinator execution-history views
  • pause / resume / cancel controls

Next Steps

ArchitectureInstallation