Protocol

Architecture

Deep dive into the on-chain programs, token model, account structure, and transaction flows.

On-Chain Programs

regvault

8nGe1FgxR8tDcvrnsaC7C3o9PjypG2br4xsXQYxsfGeL

The main protocol program handling vault operations, entity registry, and compliance controls. Built with Anchor 0.32.1.

  • Vault initialization and role management
  • Entity registry (create, status updates, limits)
  • Wallet claiming and venue linking
  • Issuer attestations with expiry
  • Deposit and mint share tokens
  • Withdraw queue (request, approve, execute, cancel)
  • Immutable receipt generation
  • Pause controls and emergency mechanisms

share_hook

EduibecVcDB9oMp1uUy1WLnYJMGCMHXHwRwi7eSdg9GK

Token-2022 Transfer Hook program that validates every share transfer. This is where compliance enforcement happens at the token layer.

  • Initialize ExtraAccountMetaList for share mint
  • Execute hook validates source entity and attestation
  • Validate destination (approved venue or active entity)
  • Uses SPL TLV account resolution for deterministic PDAs

Token Model

Deposit Token (USDC)

Users deposit USDC into the vault. On localnet, this is a mock USDC mint created during initialization. On devnet/mainnet, this would be the official USDC mint.

Share Token (rvUSDC)

The share token is a Token-2022 mint with the Transfer Hook extension enabled. This extension calls the share_hook program on every transfer, enabling protocol-level enforcement of compliance rules.

Why Token-2022?

Token-2022 introduces the Transfer Hook extension, which allows programs to enforce custom logic on token transfers. This is the key innovation that enables RegVault to enforce compliance at the token layer rather than just the UI layer.

Vault Custody Accounts

Vault Deposit ATA: Holds deposited USDC, owned by the vault authority PDA.

Vault Share Escrow ATA: Holds shares during the withdraw request period, owned by the vault authority PDA.

Vault Authority PDA: Derived from ["vault_authority", vault_config]. Signs mints, burns, and transfers on behalf of the vault.

Account Structure

All protocol accounts are Program Derived Addresses (PDAs) for deterministic addressing and cross-program invocation safety.

VaultConfig

Seeds: ["vault_config", vault_id]

Central configuration: roles, policy, limits, mints, pause flags

Entity

Seeds: ["entity", vault_config, entity_id]

Institutional entity with status, tier, jurisdiction, and caps

EntityWallet

Seeds: ["entity_wallet", vault_config, wallet]

Wallet-to-entity binding with active flag

Attestation

Seeds: ["attestation", vault_config, entity, issuer]

Issuer-signed compliance attestation with expiry

WithdrawRequest

Seeds: ["withdraw_request", vault_config, request_id]

Withdrawal queue entry with approvals and timelock

Receipt

Seeds: ["receipt", vault_config, request_id]

Immutable audit evidence of execution

DailyWithdrawCounter

Seeds: ["daily_counter", vault_config, entity, epoch_day]

Per-entity daily withdrawal tracking

Transaction Flows

Deposit Flow

  1. User calls deposit(amount) with valid entity wallet and attestation
  2. Program validates: wallet active, entity active, attestation valid and not expired
  3. Program checks entity deposit cap
  4. USDC transferred from user ATA to vault deposit ATA
  5. Vault authority mints rvUSDC shares to user share ATA
  6. Entity total_deposited incremented

Withdraw Flow

  1. Request: User calls request_withdraw(shares, amount_quote)
    • Shares transferred from user to escrow via Transfer Hook
    • WithdrawRequest PDA created with timelock and approval requirements
  2. Approve: Operator and/or Compliance call approve_withdraw
    • Approval flags tracked via bitmap
    • Required approvals determined by amount threshold
  3. Execute: Operator/Compliance calls execute_withdraw after timelock expires
    • Shares burned from escrow
    • USDC transferred from vault to destination
    • Immutable Receipt PDA created

Share Transfer Flow (P2P)

  1. Any Token-2022 transfer invokes the Transfer Hook
  2. Hook resolves EntityWallet and Attestation PDAs for source
  3. Hook validates source: active entity, valid attestation
  4. Hook checks if destination is approved venue
  5. If not venue, resolves and validates destination entity/attestation
  6. Transfer succeeds only if all checks pass

Tip

The Transfer Hook runs on every transfer, including those initiated outside the RegVault UI. This is the key to bypass-resistant compliance.

Role-Based Access Control

Admin

  • Initialize vault config
  • Set roles (compliance, operator, emergency)
  • Manage allowed issuers and primary issuer
  • Set approved venues
  • Pause/unpause operations
  • Set policy thresholds

Compliance

  • Create and manage entities
  • Set entity status and limits
  • Link/unlink venue wallets
  • Approve withdrawals
  • Sign attestations (if also issuer)

Operator

  • Approve withdrawals
  • Execute approved withdrawals after timelock
  • Monitor queue and system health

Emergency Admin

  • Pause operations in emergency
  • Unpause only if explicitly allowed by admin
  • Cannot perform other admin actions
Next: Transfer Hook →