Vaulx Protocol

The on-chain credit rail for physical luxury collateral. Borrowers deposit watches, jewellery, and fine objects into licensed custody; loans settle in USDC on Solana, with every state transition enforced by four Anchor programs.

Submitted to the Solana Frontier Hackathon (Colosseum), May 2026.

• 🌐 Live demo — vaulx.fi
• 📺 Demo UI code — site/ (Laravel borrower + admin flows that power the live demo)
• 🔐 Upgrade authority — Squads V4 multisig PDA 99o9WXdP3Gt1wwnYtEXheTh5x599f6SfmAdn9um3hejR

---

What this protocol does

Asset-rich borrowers in emerging markets are trapped behind broken credit infrastructure: pawn monopolies value luxury watches as scrap metal, while institutional USDC liquidity sits on-chain unable to reach off-chain collateral. Vaulx is the rail between the two.

The flow:

1. Borrower deposits a physical asset (watch, jewellery) with a licensed custodian (Brink's, Loomis, Prosegur).
2. A Metaplex Bubblegum cNFT is minted representing the asset, holding the full physical record (model, value, custody location, insurance, settlement contract).
3. The borrower locks the cNFT and borrows USDC against it.
4. A single atomic instruction transitions loan state, debits the vault, and disburses USDC to the borrower's ATA — gated by an on-chain custody confirmation from the licensed counterparty. No USDC is released without that confirmation.
5. Repayment in USDC unlocks the cNFT. On default, a permissionless Dutch auction triggers.

Vaulx orchestrates licensed counterparties — it does not take custody and does not hold capital. All settlement is on-chain.

---

Architecture — four Anchor programs

All four programs are deployed to Solana Devnet. Upgrade authority is held by a Squads V4 2-of-3 multisig with timelock — no single key controls protocol funds or code.

Program	Address	Purpose
trdc	AjW6tvZ1PAugf7TY6Ve3V5DuJZ39y1nwsng2JG3k7Qcp	Loan state machine. The only program authorized to mint the compressed-NFT representation of a collateralized asset.
vault	E8UjmXc8RdfbB3qfVqu3bV5uzBLxPWMsVMRqe2FPJhrh	USDC reserve with share-based accounting and KYC gate. Only loan can move funds out via CPI.
loan	4Ufx2hZu4ZcdJ2ySTuju9BDfonBHyNUgdkBZCYTGKmDV	Orchestrates origination, atomic custody confirmation, disbursement, repayment, and renewal.
auction	3U7DeXF37R1MBtMio6Ex5yuHAUiHUY3WXYoHUzN1ApqM	Permissionless Dutch-auction foreclosure on default.

Each program is in its own crate under programs/. Compromising any single program cannot drain the system — the vault enforces a two-layer authority gate (PDA + Instructions-sysvar verification) before releasing funds.

---

The atomic invariant

The load-bearing technical decision is the confirm_custody + disburse instruction in programs/loan/. A single signed transaction does three things atomically:

1. Transitions loan state Pending → ActiveInCustody.
2. CPIs into the vault program to disburse USDC into the borrower's pre-pinned associated token account.
3. Transitions loan state ActiveInCustody → Active.

The borrower's USDC destination is pinned to the borrower's public key in the accounts struct itself — the licensed custodian, who is the only signer of the confirm, cannot redirect funds.

No USDC moves until that confirmation lands on-chain. Human trust on the physical-asset side; cryptographic guarantee on the money side.

---

On-chain proof — verified devnet transactions

These instructions have been executed against the deployed programs above and can be inspected on Solana Explorer:

Instruction	Signature	What it proves
Atomic confirm_custody + disburse	5Vny6HYe…AGgP	One signed tx: ConfirmCustody → ConfirmCustodyTransition → Disburse → TransitionToActive. The load-bearing tech: no USDC moves until the licensed custodian confirms on-chain.
create_ccb_trdc	52SUbPcE…MtGL	CCB (Cédula de Crédito Bancário) creation + TRDC state initialisation — the legally-binding loan instrument anchored to the on-chain state.
init_vault	c8NccpWz…aDoxP7	USDC reserve initialised for this asset mint.
deposit (LP capital)	5ynYJcgf…TPqDc	LP capital deposited; vault shares minted.

Click the 5Vny6HYe… signature first — it's the single transaction where loan state transitions atomically, the borrower's USDC ATA is debited from the vault PDA, and the loan ends in the Active state. All four state changes in one signed instruction.

Supporting records committed to this repo:

• scripts/dev/edson-devnet.json — current deployment PDAs + init signatures
• scripts/dev/edson-usdc.json — Devnet USDC mint metadata
• scripts/dev/devnet-deploy.json — program-deploy record
• scripts/dev/squads-upgrade-history.json — multisig authority-transfer history

---

Stack

• Programs: Rust + Anchor 0.30.1
• Off-chain bridge: Node + Express + @coral-xyz/anchor (apps/bridge/)
• Indexer: TypeScript event tail → Supabase (apps/indexer/)
• App: Next.js 14 + Tailwind + shadcn/ui (apps/web/)
• Identity: Crossmint smart wallets + Sumsub WebSDK (KYC), with reusable on-chain attestation via Solana Attestation Service
• Compressed NFT: Metaplex Bubblegum + SPL account compression
• Oracles: Pyth (price) — wired, gated off in demo per hackathon scope
• Governance: Squads V4 multisig (2-of-3 timelock) holds upgrade authority on all four programs
• Tests: mocha + chai for Anchor programs (88 specs across tests/); vitest workspace-wide (135 specs across apps/ + packages/) — 223 total
• Toolchain: pnpm workspaces, Turborepo

---

Quick start

Prerequisites: Node 18+, pnpm 10+, Rust + Anchor 0.30.1, Solana CLI 1.18+.

git clone https://github.com/Vaulxfi/vaulx-protocol.git
cd vaulx-protocol
pnpm install

# Run the workspace-wide test suite (vitest)
pnpm test

# Run the Anchor program tests (in-process validator)
anchor test

Each program can be built and deployed individually:

anchor build
anchor deploy --provider.cluster devnet

To re-run an end-to-end "moment" against your own keypair on Devnet:

pnpm exec tsx scripts/dev/moments-5-9-e2e.ts

---

Repository layout

programs/
  trdc/       Loan state machine + cNFT minter
  vault/      USDC reserve, KYC gate, share accounting
  loan/       Origination, custody confirmation, repay/renew
  auction/    Permissionless Dutch-auction foreclosure

apps/
  bridge/     Node service: typed reads + loan-lifecycle writes (HMAC auth)
  indexer/    TS worker: tails on-chain events → Supabase
  web/        Next.js 14 borrower/lender product UI

packages/
  anchor-client/    Typed clients per program
  idls/             Generated IDLs + types (@vaulx/idls)
  ccb/              CCB (Cédula de Crédito Bancário) PDF + SHA-256
  supabase/         Schema + typed queries
  terms/            Loan terms types
  types/            Shared TS types

scripts/dev/    Devnet deploy + smoke-test artifacts
                Squads multisig setup + upgrade history
                End-to-end "moments" runners

site/           Laravel demo UI — borrower + admin flows that power
                the live demo at vaulx.fi. Self-contained PHP app
                (Blade + Vite + SQLite). Migrated from Vaulxfi/site.

tests/          mocha specs for the 4 programs + 3 e2e moments
supabase/       Postgres migrations for the indexer

---

Security posture

• No protocol-owned custody. Vaulx orchestrates licensed counterparties; the team does not hold physical assets.
• No protocol-owned capital. USDC sits in on-chain vault PDAs; the team has no withdraw authority.
• Upgrade authority: Squads V4 multisig PDA 99o9WXdP3G…hejR with 2-of-3 threshold and timelock.
• Two-layer authority gate on the vault: disburse callers must (1) be the loan-program PDA signing via invoke_signed, and (2) the top-level instruction must be owned by the loan program (verified via the Instructions sysvar). Closes CPI-substitution.
• First-loss buffer: 5% protocol-owned liquidity reserve absorbs the first slice of any default before LP capital.
• KYC gate + price oracle: implemented on-chain, toggled false in this demo per hackathon scope.

---

License

MIT — see LICENSE.

---

Team

• George Dimitrov — CEO · 15+ years in banking operations
• Marcelo Coelho — Chief Operations · Brazilian physical-security infrastructure
• Rodrigo Coelho — Chief Growth · institutional network, market entry across LATAM
• Edson Pohren — Senior Engineer · Anchor · Bubblegum · oracle integration
• Felipe Veloso — DeFi Advisor & Community · founder of 4p.finance

Contact: hello@vaulx.fi