Frequently Asked Questions

Yes, you can interact directly with the programs using the Solana CLI, custom scripts, or other UIs. However, the Transfer Hook enforcement cannot be bypassed.

Every share transfer (rvUSDC) triggers the share_hook program which validates:

• Source wallet belongs to an active entity
• Entity has a valid, non-expired attestation from the primary issuer
• Destination is either an approved venue or another active, attested entity

Direct program interaction works for deposits, withdrawals, and admin operations. But if you try to transfer shares to an unregistered wallet, the Transfer Hook will reject it, even if you construct the transaction manually.

Token-2022 introduces the Transfer Hook extension, which allows a program to enforce custom validation logic on every token transfer. This is the key innovation that enables RegVault to enforce compliance at the token layer.

With standard SPL tokens:

• Compliance must be enforced in program instructions only
• Users can bypass restrictions by transferring tokens directly
• Shares could freely circulate to any wallet

With Token-2022 Transfer Hooks:

• Compliance follows the asset itself
• Every transfer is validated, regardless of origin
• Shares remain permissioned within the institutional perimeter

RegVault stores only cryptographic hashes and codes on-chain, not personal information like names, addresses, or government IDs. This design choice provides several benefits:

• Privacy: On-chain data is public. Storing PII would expose sensitive information.
• Compliance: Many jurisdictions restrict how PII can be stored and transmitted. Hash-based attestations avoid these issues.
• Flexibility: Issuers can define their own claim schemas off-chain while maintaining a standard on-chain interface.

The claim_hash in an attestation commits to off-chain data. Issuers and auditors can verify the full claim data against this hash without exposing it on-chain.

Withdrawals require approval from both Operator and Compliance roles for amounts above a threshold. This creates a separation of duties that prevents unilateral fund movement.

The approval flow:

1. User requests withdrawal (shares move to escrow)
2. Required approvals determined by amount (1 or 2)
3. Operator and/or Compliance call approve_withdraw
4. Approvals tracked via bitmap (0b01 = Operator, 0b10 = Compliance)
5. Once threshold met, request enters Approved status
6. After timelock expires, either role can execute

The requester can cancel at any time before execution, returning shares from escrow. This provides an escape hatch if the user changes their mind or detects suspicious activity.

Deploying to devnet involves three steps:

1. Deploy programs:
   pnpm deploy:devnet
   This deploys both regvault and share_hook programs to devnet.
2. Initialize protocol:
   pnpm init:devnet
   This creates mints, initializes the vault config, and sets up roles. Save the printed environment variables.
3. Configure web app:
   Copy the environment variables to apps/web/.env.local and deploy to Vercel or run locally.

If airdrops fail during initialization, fund the printed keypairs from the Solana Faucet and re-run pnpm init:devnet.

If an entity attestation expires, the Transfer Hook will reject any share transfers involving that entity. This affects:

• Direct share transfers from the entity wallets
• Withdrawal requests (shares cannot be moved to escrow)
• Receiving shares from other entities

The entity remains in the registry but is effectively frozen until the attestation is refreshed. Compliance or the issuer can update the attestation with a new expiry date to restore functionality.

No. The emergency admin role is intentionally limited. It can only pause operations (deposits and withdrawals). It cannot:

• Approve or execute withdrawals
• Move funds from vault accounts
• Change roles or policy
• Create or modify entities

By default, the emergency admin cannot unpause either. This requires the admin to explicitly set allow_emergency_unpause = true. This ensures the emergency role is strictly for incident response, not operational control.

While Solana provides transaction history via RPC, Receipts in RegVault serve a specific audit purpose:

• Immutable: Receipt PDAs exist as long as the account rent is maintained, independent of RPC retention.
• Structured: Contains parsed, relevant fields (entity, amount, destination, policy version) rather than raw transaction logs.
• Attestation Context: Records the attestation issuer and policy version at time of execution for compliance verification.
• Discoverable: Deterministic PDA derivation allows efficient querying by request ID.

Think of transaction history as the raw log, and receipts as the official record designed for audit and compliance purposes.

The ExtraAccountMetaList is a PDA that tells the Token-2022 program what additional accounts to pass to the Transfer Hook. It is a critical component of the hook mechanism.

Without it:

• The hook would not know which EntityWallet and Attestation accounts to load
• Every transfer would need client-side account resolution
• Wallets and explorers would not know how to construct valid transfers

RegVault uses the official SPL TLV (Type-Length-Value) format for the ExtraAccountMetaList, which includes seed definitions for dynamic PDA resolution. This allows the Token-2022 program to automatically derive the required accounts from the source and destination token accounts.

RegVault is designed as a reference implementation and proof of concept. While it demonstrates institutional-grade patterns, production use would require:

• Professional security audit of the Rust programs
• Proper NAV/oracle integration for share pricing
• Compliance review for your specific jurisdiction
• Operational procedures for key management and attestation workflows
• Potential program modifications for your specific requirements

The architecture and patterns are suitable for adaptation, but treat this as a starting point rather than a production system out of the box.