Cross-Chain Lending Protocol between Stacks and EVM Networks

StackLend is a revolutionary decentralized finance (DeFi) protocol that enables seamless cross-chain lending by using STX as collateral on Stacks blockchain to borrow tokens on EVM-compatible networks. The protocol bridges Bitcoin's security through Stacks with the liquidity of Ethereum-based ecosystems.

• Cross-Chain Lending: Use STX as collateral to borrow tokens on multiple EVM networks
• Stacks Integration: Leverage Bitcoin's security through Stacks blockchain
• Multi-Network Support: Currently supports Scroll Sepolia with plans for more networks
• Real-Time Relayer: Automated cross-chain transaction processing
• User-Friendly Interface: Modern React frontend with wallet integration
• Secure Smart Contracts: Audited and battle-tested contract architecture

The protocol consists of four main components:

graph TB
    A[Frontend dApp] --> B[Stacks Contracts]
    A --> C[EVM Contracts]
    B --> D[Cross-Chain Relayer]
    D --> C
    
    B --> E[STX Collateral]
    C --> F[Token Borrowing]
    D --> G[Event Processing]

1. Frontend (stacklend-fe): React-based user interface with Stacks and EVM wallet integration
2. Stacks Contracts (stacklend-stacks): Clarity smart contracts for collateral management
3. EVM Contracts (stacklend-evm): Solidity contracts for token borrowing and lending
4. Relayer (stacklend-relayer): Node.js service for cross-chain event processing

• Stacks Testnet Collateral-V1: Stacks Explorer
• Stacks Testnet Lending-V1: Stacks Explorer
• Scroll Sepolia: Scrollscan Testnet

• Node.js 18+ and npm/pnpm
• Git
• Stacks wallet (Hiro Wallet, Leather, etc.)
• MetaMask or compatible EVM wallet

1. Clone the repository

   git clone https://github.com/xfajarr/stacklend.git
   cd stacklend

2. Install dependencies for each component

   # Frontend
   cd stacklend-fe
   npm install
   
   # Relayer
   cd ../stacklend-relayer
   npm install
   
   # Stacks contracts (optional, for development)
   cd ../stacklend-stacks
   npm install

3. Configure environment variables

   # In stacklend-relayer/
   cp .env.example .env
   # Edit .env with your RPC URLs and private keys

4. Start the development servers

   # Terminal 1: Start relayer
   cd stacklend-relayer
   npm start
   
   # Terminal 2: Start frontend
   cd stacklend-fe
   npm run dev

5. Access the application

   • Frontend: http://localhost:5173
   • Relayer API: http://localhost:3000

1. Deposit Collateral: Users deposit STX tokens as collateral on Stacks blockchain
2. Request Borrow: Users specify the token and amount they want to borrow on EVM networks
3. Cross-Chain Processing: The relayer monitors Stacks events and processes requests
4. Token Minting: EVM contracts mint/transfer requested tokens to user's EVM address
5. Repayment: Users repay borrowed tokens on EVM to unlock their STX collateral

cd stacklend-fe
npm run dev        # Start development server
npm run build      # Build for production
npm run lint       # Run linting

Stacks Contracts:

cd stacklend-stacks
clarinet check     # Check contract syntax
clarinet test      # Run tests
clarinet deploy    # Deploy to testnet

EVM Contracts:

cd stacklend-evm
forge build        # Compile contracts
forge test         # Run tests
forge script script/Deploy.s.sol --rpc-url $RPC_URL --broadcast  # Deploy

cd stacklend-relayer
npm run dev        # Start with hot reload
npm test           # Run tests
npm run docker     # Build Docker image

1. Get Testnet Tokens

   • STX: Stacks Testnet Faucet
   • Scroll Sepolia ETH: Scroll Faucet

2. Connect Wallets

   • Configure Stacks wallet for testnet
   • Add Scroll Sepolia network to MetaMask
   • Network Details:
     • Name: Scroll Sepolia
     • RPC URL: https://sepolia-rpc.scroll.io/
     • Chain ID: 534351
     • Currency: ETH
     • Explorer: https://sepolia.scrollscan.com/

3. Test Flow

   • Deposit STX collateral
   • Request token borrow
   • Verify token receipt on EVM
   • Test repayment flow

• Frontend Integration Guide
• Stacks Contract Documentation
• EVM Deployment Guide
• Relayer Setup Guide

We welcome contributions! Please read our contributing guidelines and submit pull requests for any improvements.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

• All smart contracts have been tested extensively
• Cross-chain transactions are validated by the relayer
• Multi-signature support for critical operations
• Regular security audits and updates

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

• Website: [Coming Soon]

⚠️ Disclaimer: This protocol is currently in testnet phase. Use at your own risk and never deposit more than you can afford to lose. Always verify contract addresses before interacting with the protocol.