PrivateCredit Graph

Creditcoin CC3 Testnet Hackathon Official Submission
Official Web dApp: https://privatecredit-beige.vercel.app/
Live API Gateway: https://privatecredit.onrender.com
Autonomous Cross-Chain Credit Underwriting & Peer-to-Peer Lending Marketplace built natively for Creditcoin CC3 Testnet (Chain ID 102031), powered by Attestcoin Universal Smart Contracts (USC) and Creditcoin's native 0x0FD2 BlockProver precompile.

---

Executive Overview

Uncollateralized and under-collateralized lending in Web3 requires verifiable, tamper-proof credit history across disparate blockchains. PrivateCredit Graph brings a visual, graph-first intelligence workspace to credit underwriting.

By ingesting cross-chain reputation data (Ethereum Mainnet/Sepolia inflows, Arbitrum repayments, and cross-chain obligations) via the @gluwa/usc-sdk, evidence is proved against Creditcoin's native 0x0FD2 BlockProver precompile. Once verified on-chain via USCVerifier.sol, an off-chain Risk Engine evaluates the borrower's evidence graph to issue a deterministic Eligibility Badge and maximum LTV / Credit Capacity bounds on Creditcoin.

---

Key System Features

1. Native Creditcoin USC & 0x0FD2 Precompile Proofing

• Uses @gluwa/usc-sdk proof builder service to construct SPV header continuity and Merkle receipt proofs.
• Executes USCVerifier.verifyEvidence() directly against Creditcoin's 0x0FD2 precompile.
• Rejects replayed evidence, unconfigured source tokens, and invalid cross-chain transfer semantics.

2. Graph-First Underwriting Terminal (DAG Visualizer)

• Visualizes borrower reputation as a Directed Acyclic Graph (DAG) using ReactFlow:
  • Wallet Node: Root credit identity.
  • Evidence Node: Verified cross-chain inflow / repayment records.
  • Eligibility Node: On-chain badge committing verified evidence history.
  • Loan Node: Active loans, interest rate, duration, and vault status.
  • Auction Node: Collateral liquidation Dutch auctions for defaulted loans.

3. Institutional Credit Marketplace & Vault Escrow

• LoanMarketplace.sol: Borrower request creation, max APR matching, and lender offer submission.
• LoanVault.sol: Escrow vault managing loan origination, collateral locking, interest calculation, and repayment releases.
• CapacityManager.sol: Prevents over-borrowing by enforcing active credit limits across multiple concurrent loans.

4. Collateral Liquidation Auctions

• DebtAuctionManager.sol: Lenders can trigger an on-chain Dutch auction for defaulted loans to liquidate locked collateral and recover principal.

5. Zero-Trust Auditor Workspace

• ArtefactRegistry.sol: Protocol auditors and judges can commit immutable keccak256 graph state snapshots to the Creditcoin ledger for complete historical auditability.

---

Live Creditcoin CC3 Testnet Deployment Registry

All core smart contracts are compiled with Solidity 0.8.23 (viaIR optimizer enabled) and deployed live on Creditcoin CC3 Testnet (Chain ID 102031):

Smart Contract	Deployed Contract Address	Explorer Link
LoanMarketplace	0xDEf64f40AfFeFD2182148cdFCeF8DAf81EC99C9a	Blockscout
LoanVault	0x84e16815CfA7FacABac6678eC1B0CdE5Fc52B5AF	Blockscout
EligibilityRegistry	0xd106C554567470b5a8a0894b3A210D175d4fD7BA	Blockscout
CapacityManager	0xBDCd79e468a05BaD60cc0822Df42c11B4e0E4f3D	Blockscout
DebtAuctionManager	0x33526D6AF4d1A7c925274dA542Eb2b06eE342b72	Blockscout
ArtefactRegistry	0x4DbBd27F6e557860564bD1aa8e0596d62a2735C4	Blockscout
USCVerifier	0x6c35e07Ca0E0234220145F33f8Bedb41eFde45b6	Blockscout
EvmV1Decoder	0x70BD41c4A9E7c849337549CD6EEb71266f2Ddd96	Blockscout
RepaymentRegistry	0xa2DBeB94c0a151e071A6c29999FE1c6B38217b85	Blockscout
USC BlockProver Precompile	0x0000000000000000000000000000000000000FD2	Native Precompile

---

Technical Architecture

                               ┌────────────────────────────────────────┐
                               │   Cross-Chain Source Transactions      │
                               │   (Ethereum Sepolia / Mainnet / Arb)   │
                               └──────────────────┬─────────────────────┘
                                                  │
                                                  ▼
                               ┌────────────────────────────────────────┐
                               │   @gluwa/usc-sdk Proof Builder         │
                               │   (SPV Header & Merkle Proof Gen)      │
                               └──────────────────┬─────────────────────┘
                                                  │
                                                  ▼
                               ┌────────────────────────────────────────┐
                               │   Creditcoin Native 0x0FD2 Precompile  │
                               │   (On-Chain BlockProver Verification)  │
                               └──────────────────┬─────────────────────┘
                                                  │
                                                  ▼
 ┌──────────────────────┐      ┌────────────────────────────────────────┐      ┌──────────────────────┐
 │ Eligibility Registry │ ◄─── │           USCVerifier.sol              │ ───► │  Risk Policy Engine  │
 │ (On-Chain Badges)    │      │ (Validates Receipts & Transfers)       │      │  (Insight Scores)    │
 └──────────┬───────────┘      └────────────────────────────────────────┘      └──────────────────────┘
            │
            ▼
 ┌──────────────────────┐      ┌────────────────────────────────────────┐      ┌──────────────────────┐
 │ Capacity Manager     │ ◄─── │          LoanMarketplace.sol           │ ───► │  Debt Auction Mgr    │
 │ (Credit Line Bounds) │      │  & LoanVault.sol (Escrow Vault)        │      │  (Collateral Bids)   │
 └──────────────────────┘      └────────────────────────────────────────┘      └──────────────────────┘

---

Repository Structure

contracts/              Solidity source files (*.sol) and unit tests (*.t.sol)
  ├── core/             LoanMarketplace, LoanVault, CapacityManager, DebtAuctionManager, etc.
  ├── usc/              USCVerifier, EvmV1Decoder
  └── interfaces/       Interface definitions for core system components
config/                 Deployment manifests (deployments.json, privatecredit-cc3-live-v3.json)
backend/                Express + TypeScript API server & risk policy engine
  ├── src/services/     GraphStore, AttestcoinService, EventStream (SSE), AssessmentService
  ├── src/policy/       PolicyEngine (Risk tier & LTV score calculator)
  └── src/routes/       REST endpoints for evidence, graph, loans, auctions, and judge view
frontend/               React + Vite + Wagmi v2 + RainbowKit v2 + ReactFlow dApp
  ├── src/components/   GraphCanvas, Inspector, CustomConnectButton, Nodes
  └── src/views/        ReputationView, LoansView, JudgeView
scripts/                Deployment & configuration scripts
test/                   Integration tests for Hardhat & Mocha

---

Required Environment Setup

Copy .env.example to root and backend/.env. Sensitive private keys and environment variables are strictly ignored from source control.

Root & Backend .env

APP_MODE=live
CREDITCOIN_RPC_URL=https://rpc.cc3-testnet.creditcoin.network
CREDITCOIN_PROOF_BUILDER_URL=https://proof-gen-api.cc3-testnet.creditcoin.network/
DEPLOYER_PRIVATE_KEY=your_funded_deployer_key
USC_VERIFIER_ADDR=0x6c35e07Ca0E0234220145F33f8Bedb41eFde45b6
SOURCE_CHAIN_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/your_key
SOURCE_CHAIN_ID=11155111
SOURCE_CHAIN_KEY=1

Frontend .env (frontend/.env)

VITE_REOWN_PROJECT_ID=your_reown_project_id
VITE_USC_VERIFIER_ADDRESS=0x6c35e07Ca0E0234220145F33f8Bedb41eFde45b6
VITE_API_URL=/api

---

Quickstart & Local Execution

1. Start the Backend API

cd backend
npm install
npm run typecheck
npm run dev

Backend runs on http://localhost:3001.

2. Start the Frontend App

cd frontend
npm install
npm run dev

Frontend runs on http://localhost:5174 (or http://localhost:5173).

---

Validation & Testing

Run the full automated test suite to verify contract invariants, policy engine logic, and frontend build integrity:

# Test smart contracts
npm run compile
npm test

# Test backend API
cd backend && npm run typecheck

# Test frontend build
cd ../frontend && npx tsc -b --noEmit

---

License

This project is licensed under the MIT License - see the LICENSE file for details.