Skip to content

VitalR/cre-vaultguard

BranchesTags

Repository files navigation

VaultGuard

Chainlink CRE Built with Foundry License: MIT

CRE-Orchestrated Tokenized Vault with Proof-of-Reserves Safeguards

VaultGuard is a tokenized ERC-4626 vault that automatically enforces risk and compliance safeguards when off-chain financial conditions change.

The system uses a Chainlink CRE workflow to verify reserve and NAV attestations, evaluate risk signals, and update an on-chain Proof-of-Reserves feed that determines how the vault operates.

Depending on the latest verified conditions, the vault dynamically transitions between:

  • NORMAL — deposits and withdrawals allowed
  • LIMITED — deposits disabled, withdrawals capped per epoch
  • PAUSED — all operations halted for safety

Project TL;DR

VaultGuard demonstrates how Chainlink CRE can turn off-chain financial verification into deterministic on-chain safeguards.

The system combines:

  • CRE orchestration — Chainlink workflows fetch, verify, and deliver reports on-chain
  • Proof-of-Reserves verification — signed reserve/NAV attestations determine vault operating modes (NORMAL, LIMITED, PAUSED)
  • ACE policy enforcement — compliance controls such as allowlists and transaction limits
  • Optional AI risk signals — an automated risk sentinel that can temporarily tighten vault conditions

Real-World Use Case

Tokenized asset vaults often depend on off-chain information such as:

  • custodian reserve balances
  • NAV calculations from fund administrators
  • liabilities or issuance levels
  • compliance signals or operational alerts

If these signals deteriorate or become stale, a vault should automatically restrict activity to protect users.

VaultGuard demonstrates how Chainlink CRE bridges off-chain financial truth to deterministic on-chain safeguards.

Why it matters

Many tokenized financial systems rely on offchain trust assumptions.

VaultGuard shows how Chainlink CRE can collapse complex off-chain verification workflows into on-chain safety guarantees, ensuring vault behavior automatically adapts to real-world conditions.

Key Innovations

  • CRE-Orchestrated Proof-of-Reserves Control Plane
    VaultGuard uses Chainlink CRE to fetch, verify, and apply signed off-chain reserve reports that directly change vault behavior on-chain.

  • Deterministic Risk Enforcement for Tokenized Vaults
    Reserve health and attestation freshness are translated into explicit vault operating modes: NORMAL, LIMITED, and PAUSED.

  • Compliance + Risk in the Same On-Chain System
    Chainlink ACE policies enforce allowlists and transaction size constraints alongside vault-wide safeguard modes.

System Guarantees

VaultGuard enforces several safety guarantees through deterministic on-chain logic.

  • Attestation freshness protection
    If reserve attestations become stale, the vault automatically transitions to PAUSED.

  • Reserve health enforcement
    Degraded reserve conditions automatically trigger LIMITED mode, preventing new deposits while allowing exits.

  • Deterministic enforcement
    All vault behavior changes are enforced on-chain through the PoRFeed state and cannot be bypassed by off-chain actors.

  • Authenticated report delivery
    Keystone Forwarder → Receiver restricts who can update PoRFeed/vault state.

  • Compliance enforcement
    Chainlink ACE policies ensure allowlists and transaction limits are applied during every user interaction.

  • Bounded AI influence
    AI signals may tighten conditions (e.g. NORMAL → LIMITED) but cannot relax deterministic safety rules.

Architecture at a glance

VaultGuard connects off-chain financial verification with deterministic on-chain vault safeguards using a Chainlink CRE workflow.

System flow

Off-chain attestations
→ Chainlink CRE verification workflow
→ Proof-of-Reserves on-chain state
→ VaultGuard ERC-4626 risk enforcement
→ ACE compliance checks on user actions

Key safety mechanisms

  • Proof-of-Reserves verification updates vault operating modes (NORMAL, LIMITED, PAUSED)
  • Chainlink ACE policies enforce allowlists and transaction limits
  • CRE workflows replace manual bots with deterministic orchestration
  • AI risk sentinel (optional) can temporarily tighten vault conditions
flowchart LR

A[Attestation Server<br>Signed reserve reports]
B[Chainlink CRE Workflow<br>Verification + evaluation]
C[VaultGuardPoRFeed<br>Reserve state]
D[VaultGuard ERC4626<br>Risk enforcement]
E[Chainlink ACE<br>Compliance policies]

A --> B
B --> C
C --> D
D --> E
Loading

System Lifecycle

VaultGuard dynamically adjusts vault operations based on verified reserve conditions.

flowchart LR

A[Healthy Reserves<br/>Fresh Attestation] --> B[NORMAL Mode]

B -->|Deposits Allowed| C[Vault Operations]
B -->|Reserve Ratio Drops| D[LIMITED Mode]

D -->|Deposits Disabled<br/>Withdrawals Allowed| E[User Exits]
D -->|Attestation Stale| F[PAUSED Mode]

F -->|All Operations Blocked| G[Safety Halt]
F -->|New Healthy Attestation| B

B -.->|AI Tightening| D
Loading

Full architecture deep dive: docs/ARCHITECTURE.md.

Live Deployment

Sepolia deployment:

VaultGuard
https://sepolia.etherscan.io/address/0x3b1a5A8FC743C036A19ddB546cD7146Cc93301eF

All deployed system contract addresses and network references are listed in:

docs/DEPLOYMENTS.md

Repository Structure

VaultGuard combines smart contracts, CRE workflows, and an off-chain attestation service to create a deterministic risk control plane for tokenized vaults.

CRE-VAULTGUARD/
│
├─ attestation-server/                  # Off-chain attestation server (Node / TypeScript HTTP API)
│
├─ contracts/                           # Foundry project (Solidity smart contracts)
│  ├─ script/
│  │  └─ DeployVaultGuard.s.sol         # System deployment script
│  │
│  ├─ src/
│  │  ├─ VaultGuard.sol                 # ERC-4626 vault with RiskMode enforcement
│  │  │
│  │  ├─ por/
│  │  │  └─ VaultGuardPoRFeed.sol       # Proof-of-Reserves feed contract
│  │  │
│  │  ├─ ace/
│  │  │  └─ VaultGuardExtractor.sol     # ACE policy extractor
│  │  │
│  │  └─ interfaces/
│  │     └─ KeystoneReceiver.sol        # CRE workflow report receiver
│  │
│  └─ test/                             # Foundry test suite
│
├─ docs/                                # Project documentation
│  ├─ ARCHITECTURE.md
│  ├─ DEMO_E2E.md
│  ├─ POLICY_SYSTEM.md
│  ├─ DEPLOYMENTS.md
│  └─ TENDERLY_VTN.md
│
├─ scripts/                             # Demo scripts and operational helpers
│
├─ workflows/                           # Chainlink CRE workflows (TypeScript / YAML)
│
├─ .env                                 # Local environment variables (not committed)
├─ project.yaml                         # CRE project configuration
├─ secrets.yaml                         # CRE secrets template
│
├─ Makefile                             # CLI commands for demo and workflow control
│
└─ README.md

System Components

Onchain (Solidity / Foundry)

  • contracts/src/VaultGuard.sol
    ERC-4626 vault + RiskMode gating + ACE hooks
  • contracts/src/por/VaultGuardPoRFeed.sol
    custom Proof-of-Reserves feed
  • contracts/src/por/IVaultGuardPoRConsumer.sol
    consumer interface used by the vault
  • contracts/src/interfaces/KeystoneReceiver.sol
    CRE report receiver / onReport entrypoint
  • contracts/src/ace/VaultGuardExtractor.sol
    ACE extractor / policy wiring
  • contracts/test/mocks/MockUSDC.sol
    demo asset (6 decimals)

Offchain

  • attestation-server/
    Node/TS service providing EIP-712 signed reserve attestations

  • workflows/
    Chainlink CRE workflow that fetches + verifies attestations and writes reports onchain

Enforcement Model

Risk Modes

Mode Behavior
NORMAL deposits and withdrawals enabled
LIMITED deposits disabled, withdrawals capped
PAUSED all vault operations blocked

ACE Policies

VaultGuard integrates Chainlink ACE (Automated Compliance Engine).

Policies enforced during vault calls:

  • AllowPolicy
    only allowlisted receivers may receive shares

  • VolumePolicy
    minimum deposit size
    maximum withdraw / redeem limits

AI Risk Sentinel

AI does not control funds.

Instead, it acts as an automated risk sentinel:

  • Can tighten only (NORMAL → LIMITED)
  • Cannot trigger PAUSED
  • PAUSED remains reserved for deterministic conditions (staleness or hard reserve breaches)

Implementation:

  • Onchain toggle
    make ai-on / make ai-off

  • CRE workflow fetches AI signals when enabled

  • Logs clearly show AI path:

[HTTP: AI SIGNALS]
[AI] riskScore

Demo

The CLI demo shows the complete system loop:

  1. Healthy reserves → NORMAL mode → deposit succeeds
  2. Compliance checks → dust / non-allowlisted deposit reverts
  3. Reserve deterioration → LIMITED mode → deposits blocked
  4. Withdrawals still allowed (with caps)
  5. Stale attestation → PAUSED mode → all operations halted
  6. Optional AI signal → temporary tightening

Quickstart

Run the CLI demo (Sepolia)

Start the attestation server:

make server-start

Run the end-to-end demo:

make demo

CRE Workflow Commands

Simulate workflow:

make workflow-simulate

Broadcast workflow:

make workflow-broadcast

Full walkthrough and environment setup:
docs/DEMO_E2E.md

Tenderly Validation

VaultGuard also supports execution on a Tenderly Virtual TestNet (VTN) as an additional validation environment for CRE workflow execution and onchain enforcement observability.

Tenderly is used for:

  • explorer-visible workflow execution
  • transaction trace debugging for successful and reverted calls
  • deterministic replay on forked Sepolia state
  • faster iteration and reproducible validation in a forked environment

Run the demo on Tenderly VTN:

make server-start-tenderly
make demo-tenderly

Tenderly workflow commands:

make workflow-simulate-tenderly
make workflow-broadcast-tenderly

Full Tenderly guide:
docs/TENDERLY_VTN.md

Documentation Index

Chainlink Usage

VaultGuard integrates several Chainlink components:

Component Purpose
Chainlink CRE orchestrates reserve verification workflows
HTTP Capability fetches offchain reserve data
EVM Capability reads vault state and writes PoR updates
Chainlink ACE enforces compliance policies
Keystone Forwarder / Receiver authenticated workflow report delivery

Key implementation files:

These components together form a CRE-orchestrated control plane that connects off-chain financial attestations to deterministic on-chain vault safeguards.

License

MIT — see the repository's LICENSE

Built for

Chainlink Convergence Hackathon

About

CRE-orchestrated tokenized vault with Proof-of-Reserves safeguards and on-chain risk enforcement.

Topics

smart-contracts web3 foundry risk-management chainlink defi tokenized-assets chainlink-hackathon erc4626 ai-workflow chainlink-cre proof-of-reserves chainlink-ace tenderly-vtn

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages