USDog Codebase Documentation

Comprehensive overview of smart contracts, deployment scripts, subgraph, and frontends.

Repository Structure

At the root, this monorepo contains Solidity smart contracts, deployment scripts, a subgraph, and two frontends.

  • contracts/ — Core protocol contracts (Maker-like: Vat, Spot, Dog, Clip, Jug, Vow, End, Pot, StableCoin, Join, PriceFeed, Calc, Multicall).
  • scripts/ — Hardhat scripts for deployment, configuration, and end-to-end test flows.
  • usdog/ — The Graph subgraph for indexing on-chain data.
  • frontendnew/ — Next.js app (current UI) with RainbowKit and shadcn/ui.
  • frontend/ — Legacy React app (kept for reference).
  • test/ — Mocha/Chai tests for contracts.
  • deployments/ — Stored addresses from deployments per network.

Smart Contracts

USDog is a collateralized debt position (CDP) system inspired by MakerDAO. Key components:

  • StableCoin.sol — ERC-20 stablecoin minted/burned via joins and Vat.
  • Vat.sol — Core accounting: collateral/debt balances, urns, ilks, system-wide line/dust, move/frob.
  • Spot.sol — Collateral risk config and price feeds; sets safe collateralization via mat.
  • Dog.sol — Liquidation keeper that starts auctions when vaults are unsafe; interfaces Clip.
  • Clip.sol — Dutch auctions for liquidations with price decay via Calc.
  • Calc.sol — Price decay algorithms used by Clip (exponential, linear, stairstep).
  • Jug.sol — Stability fees (per-ilk duty) accruing over time.
  • Vow.sol — System surplus/deficit management; triggers Flap/Flop in full systems.
  • End.sol — Global settlement (emergency shutdown).
  • Pot.sol — Savings rate (DSR) for idle stablecoin deposits.
  • Join.sol — Adapters: GemJoin for collateral, DaiJoin for stablecoin.
  • PriceFeed.sol — Price oracles (Chainlink, API3, custom Doge/Shib feeders, medianizer).
  • Multicall.sol — Batch calls utility.
  • mocks/ — Mock tokens and auctions for local testing.

Support libraries: lib/DSMath.sol for fixed-point math and safety.

Data Model Highlights (Vat)

  • Urn: per-user, per-ilk position tracking collateral and debt.
  • Ilk: per-collateral risk params — debt ceiling (line), min debt (dust), rate, spot, mat.
  • System-wide: live flag, debt totals, global ceilings.

Risk & Oracles (Spot/PriceFeed)

  • Each collateral uses a pip (price feed) configured via Spot to compute spot.
  • Maintainers update oracles via scripts (API3, Chainlink, or median feeds).
  • Changing mat adjusts liquidation ratio; doc configures stablecoin debt parameters.

Liquidations (Dog/Clip/Calc)

  • Dog checks safety; when unsafe, starts a Clip auction against the urn.
  • Clip runs a price-decaying auction; bidders buy collateral to cover debt + penalty.
  • Calc defines the price step-down curve; parameters are set per-ilk.

Fees & Savings (Jug/Pot)

  • Jug accrues stability fee into the debt over time via rate increases.
  • Pot pays DSR to savers from system surplus; interacts with Vow for accounting.

Global Settlement (End)

  • Emergency process to freeze the system, allowing users to reclaim collateral or stablecoin pro-rata.

System Flows

Open Vault, Deposit, Mint

  1. User approves GemJoin for collateral token.
  2. User deposits collateral via GemJoin; Vat records ink.
  3. User frobs to generate debt; DaiJoin mints StableCoin to user.

Repay and Withdraw

  1. User approves DaiJoin; burns StableCoin to reduce debt.
  2. When safe, user withdraws collateral via GemJoin.

Liquidation

  1. Price drops; vault becomes unsafe based on spot and mat.
  2. Dog kicks an auction in Clip; bidders purchase collateral.
  3. Debt gets covered; leftover collateral and proceeds settle via Vow.

Deployment & Scripts

Hardhat scripts in scripts/ handle end-to-end setup and testing.

  • deploy.js — Deploys core contracts, joins, and oracles.
  • configure-system*.js — Configures ilks, risk params, and permissions.
  • test-*.js — Scenario scripts for CDP open/mint/repay, liquidations, etc.
  • update-price-feeds.js — Oracle pokes/updates.
  • verify-contracts.js — Etherscan or block explorer verifications.

Deployment results are written to deployments/*.json and consumed by frontends.

Subgraph

The usdog/ package defines a Graph Protocol subgraph that indexes StableCoin, Vat, and Dog/Clip events.

  • schema.graphql — Entity definitions for vaults, auctions, and protocol metrics.
  • subgraph.yaml — Event sources and mappings configuration.
  • src/mapping.ts — Event handlers that maintain derived entities.

Frontends

Next.js App (frontendnew)

  • Wallet integration via RainbowKit in src/components/providers.tsx and src/lib/wagmi.ts.
  • Contract addresses and ABIs configured in src/lib/contracts.ts.
  • Key pages: /, /vaults, /vaults/open, /stake.
  • UI primitives via shadcn/ui in src/components/ui/*.

Legacy React App (frontend)

  • Contains earlier dashboard, CDP management, and liquidation views.
  • Uses wagmi configuration under src/config/wagmi.ts and contract hooks.

Configuration

  • .env and .env.local — RPC URLs, private keys, subgraph endpoints.
  • hardhat.config.js — Networks and compiler settings for Solidity.
  • deployments/*.json — Resolved on frontend via contracts.ts.
  • Price feed settings in scripts and PriceFeed.sol implementations.

Developer Guide

Run the frontend

  1. From repo root: npm run dev (spawns frontendnew).
  2. Alternatively: cd frontendnew && npm run dev.

Deploy & configure

  1. Run node scripts/deploy.js to deploy contracts.
  2. Run configuration scripts (e.g., scripts/configure-system-final.js).
  3. Update frontendnew/src/lib/contracts.ts with deployed addresses if not auto-written.
  4. Verify addresses in deployments/*.json.

Testing flows

  • Scripted E2E: scripts/test-full-cdp.js, scripts/test-liquidations.js, and variants.
  • Unit tests: test/Stablecoin.test.js.

Troubleshooting

  • Oracles not updating: run scripts/update-price-feeds.js, check API3/Chainlink config.
  • Vault actions revert: ensure approvals to GemJoin/DaiJoin; check mat, dust, and line limits.
  • Liquidations stuck: verify Dog/Clip permissions and Calc parameters.
  • Address mismatches: reconcile deployments/*.json with frontendnew/src/lib/contracts.ts.

Glossary

  • Ilk — Collateral type configuration.
  • Urn — User vault data structure.
  • Frob — Adjust collateral and debt.
  • Mat — Liquidation ratio.
  • Spot — Risk-adjusted price.
  • Dust — Minimum debt size.
  • Line — Debt ceiling (per-ilk or global).
Last updated: 2025-10-29