Security & Threat Model
On-chain enforcement, known limitations, and the security model behind RegVault Protocol.
Threat Model
RegVault is designed to address specific threats common in institutional DeFi deployments:
Unauthorized Share Transfer
Threat: Users bypass the UI to transfer shares to unregistered wallets or non-compliant entities.
Mitigation: Token-2022 Transfer Hook validates every transfer. Source must have active entity + valid attestation. Destination must be approved venue or active entity. Enforcement is at the token layer, not the UI layer.
Stale or Expired Attestation
Threat: Entity continues trading after compliance attestation expires or is revoked.
Mitigation: Transfer Hook checks attestation expiry on every transfer. Expired attestations cause immediate transfer failure. Compliance can revoke by setting attestation active=false.
Entity Status Bypass
Threat: Suspended or revoked entity continues to hold and transfer shares.
Mitigation: Entity status (Active/Suspended/Revoked) is checked on every transfer. Only Active entities can send or receive shares. Vault operations also check entity status before deposits and withdraw requests.
Single Point of Failure (Withdrawals)
Threat: Single approver is compromised and executes unauthorized withdrawals.
Mitigation: Maker-checker pattern requires both Operator and Compliance approval for withdrawals above threshold. Timelock delay provides window for detection. Requester can cancel if suspicious.
Emergency Response
Threat: Active exploit or market event requires immediate pause of operations.
Mitigation: Emergency admin role can pause deposits and withdrawals immediately. Separate from admin to allow 24/7 monitoring without full admin access.
Role Compromise
Threat: Compliance or Operator key is compromised.
Mitigation: Admin can rotate roles via set_roles. No single role can unilaterally move funds—withdrawals require multi-approval and timelock. Compromised issuer can be removed from allowed_issuers.
On-Chain vs Off-Chain Enforcement
| Control | Enforcement | Notes |
|---|---|---|
| Share Transfer Policy | On-Chain (Hook) | Cannot be bypassed |
| Entity Active Status | On-Chain (Hook) | Checked on every transfer |
| Attestation Validity | On-Chain (Hook) | Expiry checked on-chain |
| Withdrawal Approvals | On-Chain | Bitmap tracking, distinct approvers |
| Timelock | On-Chain | Unix timestamp comparison |
| Deposit Caps | On-Chain | Per-entity limit enforcement |
| Role Assignment | On-Chain | Admin-controlled, signed TX |
| Receipt Generation | On-Chain | Immutable PDA created on execute |
| UI Role Badges | Off-Chain | Convenience only; on-chain auth is source of truth |
| Entity Metadata | Off-Chain | Only hash stored on-chain |
Known Limitations
Simplified NAV (MVP)
The current implementation uses a simplified deposit/withdraw 1:1 model. A production deployment would need proper NAV calculation with oracle integration for accurate share pricing. Circuit breaker thresholds exist but are basic.
Deposit Cap Semantics
Deposit caps track cumulative deposits, not current net exposure. A user who deposits and withdraws repeatedly could hit caps without current vault exposure reflecting this. This is acceptable for MVP but would need refinement for production.
Attestation Storage
Attestations store claim hashes, not full claim data. Off-chain systems must maintain the preimage for audit. This is intentional (no PII on-chain) but requires operational discipline.
Fixed List Sizes
allowed_issuers and approved_venues use fixed-size arrays (8 and 16 respectively) for deterministic account sizing. Large-scale deployments may need registry program separation earlier than anticipated.
No Upgrade Authority
Programs are deployed without upgrade authority in the reference implementation. This is a security feature (immutable code) but means bugs require migration to new program IDs.
Audit Considerations
Receipt Verification
Receipts are immutable on-chain evidence, but auditors should verify:
- Receipt PDA derivation matches expected seeds
- Receipt owner is the regvault program
- Request ID in receipt matches WithdrawRequest (if request account still exists)
- Policy version matches expected range for the time period
Policy Version Tracking
Both WithdrawRequest and Receipt store policy_version snapshots. This allows auditors to determine what rules were in effect at the time of request and execution, even if the vault config has since been updated.
Tip
Operational Best Practices
Key Rotation: Plan for regular rotation of Compliance and Operator keys. Admin can update roles without redeploying.
Attestation Expiry: Set attestation expiries based on your compliance review cycle. Monitor for upcoming expirations and refresh before Transfer Hook rejects transfers.
Emergency Response: Keep emergency admin key accessible to on-call personnel. Practice pause/unpause procedures in testnet.
Receipt Retention: While receipts are on-chain, maintain off-chain indices for efficient querying. The API routes provide this, but production deployments may want dedicated indexing.