LedgerGuard

Escrow-backed security bounties on Stacks (USDCx).

LedgerGuard turns security reviews (bounty programs, audit tasks, bug hunts) into a transparent, escrow-backed quest workflow. Projects ("Tavernmasters") post quests with a USDCx budget and deadline, researchers ("Hunters") submit findings, and settlement finalizes outcomes with verifiable reward distribution.

---

Table of Contents

• What it is
• Key features
• Architecture
• Where to try it
• Quickstart
• Configuration
• Smart contracts
• Frontend
• Project structure
• Roadmap

---

What it is

Security bounties are often trust-based and operationally heavy:

• hunters can’t easily verify the reward budget exists
• payouts can be delayed or disputed
• coordination happens off-chain and is hard to audit

LedgerGuard solves this with:

• an on-chain quest lifecycle
• escrow funding in USDCx for stable-denominated budgeting
• deterministic settlement rules
• a product-style UI to manage quests, hunts, and findings

---

Key features

• Quest creation (Tavernmaster)
• Join hunt + submit findings (Hunter)
• Escrow funding (USDCx)
• Settlement that finalizes the quest and triggers reward distribution
• Wallet address + USDCx balance display in the navbar
• Demo Mode for reliable hackathon demos/recordings

---

Architecture

flowchart LR
  A[Next.js App] -->|Read-only calls| B[ledgerguard-core]
  A -->|Contract calls| B
  B -->|Authorized payout| C[ledgerguard-reward]
  C -->|Token transfers| D[USDCx Token]

Loading

• Contracts: Clarity smart contracts in contracts/
• Frontend: Next.js App Router in frontend/
• Tests: Vitest + Clarinet environment in tests/

---

Where to try it

• Live demo: https://ledgerguard.gardachain.com/
• Local app: run the steps in Quickstart and open http://localhost:3000
• Demo Mode: enabled by NEXT_PUBLIC_DEMO_MODE=true (see Configuration)

---

Quickstart

Prerequisites

• Node.js 18+ (recommended)
• npm (or pnpm/yarn)
• Clarinet (for contract checking)
• A Stacks-compatible wallet (for non-demo usage)

Run the frontend

cd frontend
npm install
npm run dev

Open http://localhost:3000.

Check smart contracts (Clarinet)

clarinet check

---

Configuration

Create frontend/.env with your contract addresses and network:

NEXT_PUBLIC_STACKS_NETWORK="testnet"
NEXT_PUBLIC_CORE_CONTRACT_ADDRESS="STE91V911PDB8MJ5J70T1920M8FPA0JQXHM799HB"
NEXT_PUBLIC_CORE_CONTRACT_NAME="ledgerguard-core"
NEXT_PUBLIC_REWARD_CONTRACT_ADDRESS="STE91V911PDB8MJ5J70T1920M8FPA0JQXHM799HB"
NEXT_PUBLIC_REWARD_CONTRACT_NAME="ledgerguard-reward"
NEXT_PUBLIC_USDCX_CONTRACT_ADDRESS="ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM"
NEXT_PUBLIC_USDCX_CONTRACT_NAME="usdcx"
NEXT_PUBLIC_HIRO_BASE_URL=https://api.testnet.hiro.so/

---

Smart contracts

Contracts live in contracts/:

• ledgerguard-core.clar

  • quest lifecycle and access control
  • settlement guards (ended, funded, not settled)
  • triggers reward distribution

• ledgerguard-reward.clar

  • escrow tracking
  • payout authorization (core-only)
  • token transfer logic

Clarinet configuration is in Clarinet.toml.

---

Frontend

The product UI is in frontend/ (Next.js App Router).

Core user flows:

• Tavernmaster

  • create quest: /create-quest
  • manage quests: /my-quests (fund escrow, settle)

• Hunter

  • browse quests: /quests
  • join + submit findings: /quests/[id]
  • track hunts: /my-hunts

---

Project structure

contracts/      Clarity smart contracts
deployments/    Clarinet deployment plans
frontend/       Next.js web app
settings/       local devnet/dev config
tests/          contract tests (Vitest + clarinet env)

---

Roadmap

• Severity-weighted payouts and configurable distribution policies
• Dispute window + optional arbitration hooks
• Reputation system for hunters and Tavernmasters
• Indexing/analytics for quest history and findings
• Production-grade stablecoin funding and bridge integration