A decentralized lending platform built on Arc Network that demonstrates advanced programmable logic using USDC and EURC stablecoins, integrated with Circle Gateway for automated treasury management and cross-chain operations.

• Overview
• Live Links
• Features
• Architecture
• Tech Stack
• Installation
• Configuration
• Deployment
• Smart Contracts
• API Documentation
• Testing
• Project Structure
• Contributing
• License

Lynq is a comprehensive DeFi lending platform that showcases the power of programmable money through:

1. Advanced Programmable Logic Track: Demonstrates complex automated financial systems using USDC and EURC stablecoins with smart contract conditions, automation, and cross-chain capabilities.

2. Treasury Management Track: Implements a smart contract-based treasury system using Circle Gateway and Arc to automate allocations, distributions, and on-chain treasury operations.

The platform enables organizations to manage their treasury through smart contracts, automating fund allocation, scheduled distributions, multi-signature approvals, and programmatic fund management based on rules and triggers.

• Live Application: https://lynq-arc.vercel.app/
• Demo Video: https://youtu.be/USH-SCQFoGI
• Block Explorer: Arc Testnet Explorer

• Auto-Repay on Credit Improvement: Loans automatically repay when borrower's credit score reaches 700 or higher
• Auto-Extend on Partial Payment: Loans automatically extend by 30 days when 50% is repaid before due date
• Dynamic Interest Rate Updates: Interest rates adjust based on treasury utilization ratios
• Credit Score-Based Automation: Loan terms and conditions automatically adjust based on on-chain credit scores
• Multi-Currency Repayments: Support for USDC, EURC, and other stablecoins with automatic conversion
• Cross-Chain Capabilities: Unified balance tracking and transfers across multiple chains via Circle Gateway

• Automated Budget Allocations: Percentage-based budget allocation system with automated execution
• Scheduled Distributions: Payroll-style recurring distributions with configurable frequency
• Multi-Currency Treasury: Support for multiple stablecoins with unified accounting
• Reserve Ratio Management: Automatic enforcement of minimum 20% reserve ratio
• Circle Gateway Integration: Cross-chain USDC transfers with unified balance tracking
• Role-Based Access Control: Granular permissions for treasury, screening, and compliance agents

• Decentralized Lending: Complete loan lifecycle management from request to repayment
• Identity Verification: Soulbound tokens (SBTs) for verified user identity
• Credit Scoring System: On-chain credit scoring with dynamic updates based on repayment behavior
• Liquidity Pool Management: Automated liquidity provision and withdrawal with reserve protection
• Event Tracking: Comprehensive event emission for off-chain indexing and analytics

┌─────────────────────────────────────────────────────────────┐
│                        Frontend Layer                        │
│  Next.js + React + Privy Auth + Wagmi + TanStack Query     │
└───────────────────────┬─────────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────────┐
│                      Backend API Layer                       │
│  Express.js + TypeScript + MongoDB + Ethers.js              │
│  - User Management                                          │
│  - Loan Processing                                          │
│  - Treasury Operations                                      │
│  - Gateway Integration                                      │
└───────────────────────┬─────────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────────┐
│                    Smart Contract Layer                      │
│  Arc Network (EVM-Compatible)                               │
│                                                              │
│  ┌──────────────┐    ┌──────────────────┐                  │
│  │Verification  │    │ AgentController  │                  │
│  │    SBT       │    │  (Access Control)│                  │
│  └──────┬───────┘    └────────┬─────────┘                  │
│         │                     │                             │
│         │ verifies            │ authorizes                  │
│         ▼                     ▼                             │
│  ┌────────────────────────────────────┐                     │
│  │          LoanEngine                │                     │
│  │  (Loan Lifecycle Management)       │                     │
│  └──────────────┬─────────────────────┘                     │
│                 │                                           │
│                 │ disburses/repays                          │
│                 ▼                                           │
│         ┌───────────────┐                                   │
│         │ TreasuryPool  │                                   │
│         │(Liquidity Mgmt)│                                  │
│         └───────┬───────┘                                   │
│                 │                                           │
│         ┌───────▼────────┐                                  │
│         │GatewayManager  │                                  │
│         │(Circle Gateway)│                                  │
│         └────────────────┘                                  │
│                                                              │
│  ┌────────────────────────────────────┐                     │
│  │  MultiCurrencyManager              │                     │
│  │  (USDC/EURC/MXN Support)           │                     │
│  └────────────────────────────────────┘                     │
└─────────────────────────────────────────────────────────────┘

Core Contracts:

1. VerificationSBT.sol: Soulbound token for user identity verification
2. AgentController.sol: Role-based access control system
3. LoanEngine.sol: Core loan lifecycle management with programmable features
4. TreasuryPool.sol: Liquidity pool with automated allocation and distribution
5. GatewayManager.sol: Circle Gateway integration for cross-chain operations
6. MultiCurrencyManager.sol: Multi-currency support with exchange rate management

Test Tokens:

• TestUSDC.sol: Test USDC token for Arc testnet
• TestEURC.sol: Test EURC token for Arc testnet
• TestUSYC.sol: Test USYC token for Arc testnet

• Framework: Next.js 16
• Language: TypeScript
• UI: React 19, Tailwind CSS
• Web3: Wagmi, Viem, Privy Auth
• State Management: TanStack Query
• Identity: Worldcoin IDKit

• Runtime: Node.js 20+
• Framework: Express.js
• Language: TypeScript
• Database: MongoDB
• Web3: Ethers.js 6
• Logging: Winston
• Security: Helmet, CORS, Rate Limiting

• Language: Solidity 0.8.24
• Framework: Foundry
• Libraries: OpenZeppelin Contracts
• Network: Arc Network (EVM-compatible)
• Testing: Forge

• Node.js 18+ or 20+
• MongoDB (Atlas recommended) or local MongoDB 6+
• Foundry (for smart contracts)
• Git

git clone <repository-url>
cd "lynq original"

cd frontend
npm install
cp .env.example .env.local
# Edit .env.local with your configuration
npm run dev

cd backend
npm install
cp src/config/env.example.txt .env
# Edit .env with your configuration
npm run dev

cd contracts
forge install
forge build

Create frontend/.env.local:

NEXT_PUBLIC_ARC_RPC_URL=https://rpc.testnet.arc.network
NEXT_PUBLIC_API_URL=http://localhost:3001/api
NEXT_PUBLIC_PRIVY_APP_ID=your_privy_app_id
NEXT_PUBLIC_WORLDCOIN_APP_ID=your_worldcoin_app_id

Create backend/.env:

# Server
PORT=3001
NODE_ENV=development

# Database
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/lynq

# Arc Network
ARC_RPC_URL=https://rpc.testnet.arc.network
CHAIN_ID=5042002

# Contract Addresses
VERIFICATION_SBT_ADDRESS=0x503B21D6cd2e49F814a4fB620a6aAf3228043A8f
AGENT_CONTROLLER_ADDRESS=0x405A688E1C05DB9dee85A695F008e6926859aC4c
TREASURY_POOL_ADDRESS=0x4FdF07fEce136bf05c63Bd77FF8Fc9d6f04cF301
LOAN_ENGINE_ADDRESS=0xEC4BEA60368f3aB46355CE1f1F0D2e67B2377022
GATEWAY_MANAGER_ADDRESS=0x439153faf87CaBb9Ba5C7a5602028F242fd02E33
MULTI_CURRENCY_MANAGER_ADDRESS=0x9Ced052cAD68ae68CaE1A589edC8422608A0126e
USDC_ADDRESS=0x3600000000000000000000000000000000000000
EURC_ADDRESS=0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a

# Agent Private Key (for treasury operations)
AGENT_PRIVATE_KEY=your_private_key_here

# Screening Configuration
MIN_CREDIT_SCORE_TIER1=700
MIN_CREDIT_SCORE_TIER2=600
MIN_CREDIT_SCORE_TIER3=500
BASE_INTEREST_RATE=500
MAX_LOAN_AMOUNT=50000

# CORS
CORS_ORIGIN=http://localhost:3000

Create contracts/.env:

PRIVATE_KEY=your_private_key_here
ARC_TESTNET_RPC_URL=https://rpc.testnet.arc.network
ARC_ETHERSCAN_API_KEY=your_api_key_here

cd contracts
source .env

forge script script/Deploy.s.sol:Deploy \
  --rpc-url $ARC_TESTNET_RPC_URL \
  --broadcast \
  --verify

forge script script/DeployTreasuryUpgrade.s.sol:DeployTreasuryUpgrade \
  --rpc-url $ARC_TESTNET_RPC_URL \
  --broadcast \
  --verify

cd backend
npm run build

npm start

The backend includes vercel.json for serverless deployment on Vercel.

cd frontend
npm run build

npm start

vercel deploy

// Auto-repay when credit score improves
function autoRepayOnCreditImprovement(uint256 loanId) external

// Auto-extend loan on 50% partial payment
function autoExtendOnPartialPayment(uint256 loanId) external

// Update interest rates based on utilization
function updateInterestRatesBasedOnUtilization(uint256 newBaseRate) external

// Repay with any supported currency
function repayLoanWithToken(uint256 loanId, address token, uint256 amount) external

// Create budget allocation rule
function createAllocation(string calldata name, uint256 percentage, address destination) external

// Execute all allocations
function executeAllocations() external

// Schedule recurring distribution (payroll)
function scheduleDistribution(address[] calldata recipients, uint256[] calldata amounts, uint256 frequency) external

// Execute due distributions
function executeDistributions() external

// Deposit to Circle Gateway
function depositToGateway(uint256 amount) external

// Create burn intent for cross-chain transfer
function createBurnIntent(uint256 amount, uint256 destinationChainId) external returns (bytes32)

// Execute mint on destination chain
function executeMintWithAttestation(bytes32 intentId, address recipient, uint256 amount, uint256 sourceChainId) external

• ReentrancyGuard protection on all state-changing functions
• Role-based access control using OpenZeppelin AccessControl
• Input validation on all user inputs
• SafeERC20 for token transfers
• Minimum reserve ratio enforcement (20%)
• Credit score bounds checking (0-1000)

http://localhost:3001/api

Most endpoints require authentication via wallet signature or API key.

Get user summary including balances, credit score, and active loans.

Response:

{
  "success": true,
  "data": {
    "address": "0x...",
    "creditScore": 650,
    "isVerified": true,
    "verifiedMethods": ["worldid"],
    "activeLoans": 1,
    "totalBorrowed": 1000,
    "totalRepaid": 500,
    "outstandingBalance": 525
  }
}

Create a new loan request.

Request:

{
  "borrower": "0x...",
  "amount": 1000,
  "reason": "Business expansion"
}

Approve a loan and set interest rate.

Request:

{
  "interestRate": 500,
  "txHash": "0x..."
}

Record a loan repayment.

Request:

{
  "loanId": 1,
  "amount": 500,
  "txHash": "0x..."
}

Get treasury pool metrics including liquidity, utilization, and loan statistics.

Create a new budget allocation rule.

Request:

{
  "name": "High-Risk Loans",
  "percentage": 3000,
  "destination": "0x..."
}

Execute all active allocations, transferring funds to destination addresses.

Schedule a recurring distribution (payroll).

Request:

{
  "recipients": ["0x...", "0x..."],
  "amounts": [1000, 2000],
  "frequency": 2592000
}

Deposit USDC to Circle Gateway for cross-chain access.

Request:

{
  "amount": 10000
}

Get unified USDC balance across all chains.

Add a new supported currency.

Request:

{
  "token": "0x...",
  "symbol": "EURC",
  "rateVsUSDC": 10900
}

Repay a loan using a non-USDC currency.

Request:

{
  "loanId": 1,
  "token": "0x...",
  "amount": 1000
}

For complete API documentation, see backend/README.md.

cd contracts

# Run all tests
forge test

# Run with verbosity
forge test -vvv

# Run specific test file
forge test --match-path test/LoanEngine.t.sol

# Generate gas report
forge test --gas-report

cd backend
npm test

cd frontend
npm test

lynq/
├── contracts/                 # Smart contracts
│   ├── src/                  # Contract source files
│   │   ├── LoanEngine.sol
│   │   ├── TreasuryPool.sol
│   │   ├── GatewayManager.sol
│   │   ├── MultiCurrencyManager.sol
│   │   └── ...
│   ├── test/                 # Contract tests
│   ├── script/               # Deployment scripts
│   └── foundry.toml
│
├── backend/                  # Backend API
│   ├── src/
│   │   ├── controllers/      # API controllers
│   │   ├── models/           # Database models
│   │   ├── routes/           # API routes
│   │   ├── services/         # Business logic
│   │   └── utils/            # Utilities
│   └── package.json
│
├── frontend/                 # Frontend application
│   ├── src/
│   │   ├── app/              # Next.js app directory
│   │   ├── components/       # React components
│   │   ├── lib/              # Utilities and hooks
│   │   └── config/           # Configuration
│   └── package.json
│
└── README.md

When a borrower's credit score reaches 700 or higher, the loan automatically repays from their USDC balance:

function autoRepayOnCreditImprovement(uint256 loanId) external {
    Loan storage loan = loans[loanId];
    require(creditScore[loan.borrower] >= 700, "Credit score not high enough");
    
    uint256 userBalance = usdc.balanceOf(loan.borrower);
    uint256 remaining = getRemainingBalance(loanId);
    
    require(userBalance >= remaining, "Insufficient balance");
    
    // Auto-repay
    usdc.safeTransferFrom(loan.borrower, address(this), remaining);
    loan.repaid += remaining;
    loan.status = LoanStatus.Repaid;
}

Treasury automatically allocates funds based on percentage rules:

function executeAllocations() external onlyTreasuryAgent {
    uint256 available = totalLiquidity - totalUtilized;
    
    for (uint256 i = 1; i <= allocationCount; i++) {
        Allocation storage alloc = allocations[i];
        if (!alloc.active) continue;
        
        uint256 amount = (available * alloc.percentage) / BASIS_POINTS;
        usdc.safeTransfer(alloc.destination, amount);
        alloc.allocated += amount;
    }
}

Automated recurring distributions execute when due:

function executeDistributions() external {
    for (uint256 i = 1; i <= distributionCount; i++) {
        Distribution storage dist = distributions[i];
        
        if (!dist.active) continue;
        if (block.timestamp < dist.lastExecuted + dist.frequency) continue;
        
        for (uint256 j = 0; j < dist.recipients.length; j++) {
            usdc.safeTransfer(dist.recipients[j], dist.amounts[j]);
        }
        
        dist.lastExecuted = block.timestamp;
    }
}

The GatewayManager contract integrates with Circle Gateway to enable cross-chain USDC transfers:

1. Deposit to Gateway: Users deposit USDC into the gateway wallet
2. Create Burn Intent: Users create burn intents for cross-chain transfers
3. Attestation Verification: Circle Gateway provides attestations for valid burns
4. Mint on Destination: USDC is minted on the destination chain based on attestations

The system maintains unified balance tracking across all chains, allowing users to see their total USDC balance regardless of which chain they're on.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• Follow TypeScript best practices
• Write comprehensive tests for all new features
• Update documentation for API changes
• Follow Solidity style guide for smart contracts
• Ensure all tests pass before submitting PR

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

For issues, questions, or contributions, please open an issue on the repository or contact the development team.

• Built for Arc Circle Hackathon
• Uses OpenZeppelin Contracts for security
• Integrated with Circle Gateway for cross-chain functionality
• Deployed on Arc Network testnet