VaultFlow

AI-managed treasury vaults for European SMEs on Solana.

VaultFlow lets businesses deposit idle EURC or USDC, earn 5–10%+ APY across Kamino, Drift, and Raydium automatically, run payroll on a schedule, and move money in and out via SEPA bank transfers — without any DeFi knowledge required.

Built for the Colosseum Frontier Hackathon (April–May 2026).

Devnet Program ID: Fvs33of5snzzjFjgyY6id1RQ7sqgxX8WDvU2FMECaVqy

---

The Problem

European SMEs hold trillions of euros in bank accounts earning sub-1% annually. DeFi offers 5–15% APY on stablecoins, but the barrier is too high: protocol complexity, non-compliant assets (USDT/EURT both delisted from EU exchanges post-MiCA), no fiat rails, and no tooling built for finance teams rather than crypto natives.

The Solution

VaultFlow is the intersection of three things no other Solana vault project combines:

1. MiCA-compliant EURC exclusively. Circle holds an EU EMI license (July 2024), passported across all 27 EU member states — the only stablecoin a corporate treasurer can defend to their CFO.
2. AI agents that rebalance automatically. The agent engine fetches live APY data from Kamino, Drift, and Raydium and rebalances on-chain when allocation drifts — no DeFi knowledge required.
3. SEPA fiat rails built in. Businesses wire EUR from their bank account, earn yield, and wire back. No crypto exchange, no OTC desk.

---

Architecture

Three-layer monorepo:

programs/vault/     Anchor smart contract (Rust)
app/                Next.js 16 frontend dApp
agents/             AI agent engine (TypeScript)
tests/              Anchor integration tests (TypeScript / Mocha)
scripts/            Devnet smoke tests

Smart Contract (programs/vault/)

Six on-chain instructions:

Instruction	Description
initialize_vault	Creates a VaultAccount PDA; validates allocation weights sum to 10,000 bps
deposit	SPL token transfer from owner into vault ATA; checked_add accounting
withdraw	PDA-signed transfer back to owner
reallocate	Agent-only; reentrancy guard; computes deltas; protocol CPIs (mainnet feature flag)
schedule_payroll	Owner sets recurring payroll schedule with recipient list
execute_payroll	Permissionless once due; PDA-signed SPL transfers to each recipient

Protocol CPIs (Kamino, Drift, Raydium) are gated behind --features mainnet-protocols and skipped entirely on localnet — all 13 integration tests pass without external protocol programs.

AI Agent Engine (agents/)

Module	Role
yield-oracle.ts	Fetches live APY from Kamino strategies API, Drift spot-markets API, Raydium CLMM pools API; 5-min TTL cache with stale fallback
allocation-engine.ts	Proportional APY weighting; minReserveBps liquidity floor always kept liquid
vault-agent.ts	Poll loop: fetchRates → computeAllocation → fetch on-chain state → send reallocate tx if any field drifts > 200 bps
retry.ts	Exponential backoff with full jitter on all RPC and API calls

Frontend (app/)

Built with Next.js 16 (App Router), TypeScript, Tailwind v4, and @solana/wallet-adapter.

Route	Description
/	Treasury dashboard — vault overview, deposit/withdraw, fiat ramp
/positions	All active vaults with yield stats
/positions/[mintKey]	Individual vault detail — strategy, positions, agent activity
/create	No-code vault creation — name, token, yield strategy, initial deposit
/fiat	SEPA ↔ EURC on/off-ramp via Circle Mint API
/api/onramp	Circle wire-in API route
/api/offramp	Circle wire-out API route

---

Security

• Reentrancy guard: is_locked is set before any CPI call and explicitly cleared on every success and error path — a failing CPI can never permanently brick a vault.
• Agent-only reallocation: only the agent pubkey stored on VaultAccount can call reallocate; the owner cannot override it.
• Overflow protection: deposited_amount uses checked_add; payroll totals use try_fold + checked_add; all deltas use saturating_*.
• ATA validation: execute_payroll reads raw SPL byte layout (mint @[0..32], owner @[32..64]) — recipients cannot be spoofed via misleading account labels.
• Protocol CPIs gated: Kamino, Drift, and Raydium CPIs compile only with --features mainnet-protocols, keeping localnet tests hermetic.

---

Test Coverage

Suite	Count	Status
Smart contract integration (Anchor / Mocha)	13	Passing
Agent engine unit tests (Jest)	31	Passing
Devnet smoke test	6 steps	Passing

Smoke test golden path (live on devnet): initialize → deposit 10,000 EURC → reallocate → schedule payroll → execute payroll → withdraw

---

Prerequisites

Tool	Version
Rust	stable (1.75+)
Solana CLI	1.18+
Anchor CLI	0.31.1
Node.js	18+

# Install Solana CLI
sh -c "$(curl -sSfL https://release.solana.com/stable/install)"
export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"

# Install Anchor CLI
cargo install --git https://github.com/coral-xyz/anchor anchor-cli --tag v0.31.1

# Generate a devnet wallet
solana-keygen new --outfile ~/.config/solana/id.json
solana config set --url devnet
solana airdrop 2

---

Getting Started

git clone https://github.com/your-username/vault-flow.git
cd vault-flow
npm install

Smart contract

anchor build                          # compile + generate IDL
anchor test                           # deploy to localnet + run 13 integration tests
anchor deploy --provider.cluster devnet

Frontend

cp app/.env.example app/.env.local    # set NEXT_PUBLIC_RPC_ENDPOINT
npm run app:dev                       # http://localhost:3000
npm run app:build                     # production build

AI agent engine

cp agents/.env.example agents/.env    # fill in RPC_ENDPOINT, VAULT_PUBKEY, AGENT_KEYPAIR_PATH
npm run agent:start

Devnet smoke test

npm run smoke:devnet

---

Environment Variables

app/.env.local

Variable	Description
NEXT_PUBLIC_RPC_ENDPOINT	Solana RPC URL (defaults to devnet)
CIRCLE_API_KEY	Circle Mint API key (sandbox: app.circle.com/signup)
CIRCLE_SANDBOX	Set to true for sandbox mode

agents/.env

Variable	Description
RPC_ENDPOINT	Solana RPC URL
VAULT_PUBKEY	On-chain vault PDA address
AGENT_KEYPAIR_PATH	Path to agent keypair JSON file
REALLOC_THRESHOLD_BPS	Drift threshold before rebalancing (default: 200)
KAMINO_STRATEGY_ADDRESS	Kamino strategy account address
DRIFT_MARKET_INDEX	Drift spot market index for EURC (default: 2)
RAYDIUM_POOL_ADDRESS	Raydium CLMM pool address

See agents/.env.example for the full list.

---

MiCA & Compliance

• EURC only. USDT and EURT are both non-compliant and delisted from EU exchanges post-MiCA. VaultFlow uses EURC exclusively.
• Circle EMI license. Circle holds a MiCA Electronic Money Institution license (July 2024), valid across all 27 EU member states.
• No in-app KYB/KYC. Circle handles business account approval server-side. The dApp does not collect or process personal data.
• Smart contract transparency. All vault operations are on-chain and auditable. The agent's reallocation authority is limited to a single whitelisted pubkey per vault.

---

Deployment

The smart contract is live on Solana devnet:

Program ID:  Fvs33of5snzzjFjgyY6id1RQ7sqgxX8WDvU2FMECaVqy
Deploy sig:  5xzn89ZnadfTgYsxyYchpjbGSPUZgqkXEP1rwVDxfoswK9zFEQ9PvMD511BQic7QWZyQAdrnZRMLWFMvXge3HR1d
Explorer:    https://explorer.solana.com/address/Fvs33of5snzzjFjgyY6id1RQ7sqgxX8WDvU2FMECaVqy?cluster=devnet

---

Tech Stack

Layer	Stack
Smart contract	Rust, Anchor 0.31.1, SPL Token
Frontend	Next.js 16, TypeScript, Tailwind v4, @solana/wallet-adapter
Agent engine	TypeScript, @coral-xyz/anchor, Jest
Protocols	Kamino Lending, Drift Protocol, Raydium CLMM
Fiat rails	Circle Mint API (SEPA ↔ EURC)
Stablecoin	EURC (Circle, MiCA-compliant)
Network	Solana devnet (mainnet-ready)

---

License

MIT