SETTL.

SETTL is a Stripe-like invoice link that turns accounts receivable into RealFi rails on Mantle: businesses get paid in stablecoins, unlock instant financing against invoices/cashflows, and build an on-chain reputation that improves terms over time.

For a detailed introduction, see INTRO.md.

🏗️ Architecture

System Overview

graph TB
    subgraph "User Layer"
        Seller[👤 Seller<br/>Business]
        Buyer[👤 Buyer<br/>Customer]
        LP[💰 Liquidity Provider<br/>LP]
        Admin[⚙️ Protocol Admin<br/>Treasury]
    end

    subgraph "Frontend Layer"
        React[⚛️ React + TypeScript]
        Privy[🔐 Privy<br/>Embedded Wallets]
        Wagmi[🔗 Wagmi<br/>Web3 Hooks]
        Reclaim[🔒 Reclaim Protocol<br/>zkTLS Proofs]
        
        React --> Privy
        React --> Wagmi
        React --> Reclaim
    end

    subgraph "Mantle Network (L2)"
        subgraph "Invoice System"
            InvoiceRegistry[📋 InvoiceRegistry<br/>State Management]
            InvoiceNFT[🎨 InvoiceNFT<br/>ERC721 NFT]
            
            InvoiceRegistry -->|Mints| InvoiceNFT
        end
        
        subgraph "Financing System"
            Vault[🏦 Vault<br/>Liquidity Pool]
            USMTPlus[🪙 USMT+<br/>ERC20 Receipt]
            Staking[📊 Staking<br/>Yield Position]
            AdvanceEngine[⚡ AdvanceEngine<br/>Instant Financing]
            
            Vault -->|Mints 1:1| USMTPlus
            USMTPlus -->|Stake| Staking
            AdvanceEngine -->|Borrows| Vault
            AdvanceEngine -.->|Uses as Collateral| InvoiceNFT
        end
        
        subgraph "Settlement System"
            SettlementRouter[💸 SettlementRouter<br/>Payment Waterfall]
            Reputation[⭐ Reputation<br/>Credit Score]
            
            SettlementRouter -->|Updates| InvoiceRegistry
            SettlementRouter -->|Updates| Reputation
            SettlementRouter -->|Repays| Vault
        end
        
        DemoUSDC[💵 DemoUSDC<br/>ERC20 Stablecoin]
    end

    Seller -->|Creates Invoice| React
    Buyer -->|Pays Invoice| React
    LP -->|Deposits/Stakes| React
    Admin -->|Manages| React

    React -->|Web3 Calls| InvoiceRegistry
    React -->|Web3 Calls| Vault
    React -->|Web3 Calls| Staking
    React -->|Web3 Calls| AdvanceEngine
    React -->|Web3 Calls| SettlementRouter

    InvoiceRegistry -.->|Checks Status| AdvanceEngine
    AdvanceEngine -.->|Updates Status| InvoiceRegistry
    SettlementRouter -.->|Updates Status| InvoiceRegistry
    
    SettlementRouter -->|Fee| Admin
    SettlementRouter -->|Remainder| Seller
    
    style Seller fill:#2563eb,stroke:#1e40af,stroke-width:2px,color:#fff
    style Buyer fill:#2563eb,stroke:#1e40af,stroke-width:2px,color:#fff
    style LP fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#fff
    style Admin fill:#dc2626,stroke:#b91c1c,stroke-width:2px,color:#fff
    style React fill:#6366f1,stroke:#4f46e5,stroke-width:2px,color:#fff
    style Privy fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#fff
    style Wagmi fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#fff
    style Reclaim fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#fff
    style InvoiceRegistry fill:#10b981,stroke:#059669,stroke-width:2px,color:#fff
    style InvoiceNFT fill:#10b981,stroke:#059669,stroke-width:2px,color:#fff
    style Vault fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#fff
    style USMTPlus fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#fff
    style Staking fill:#06b6d4,stroke:#0891b2,stroke-width:2px,color:#fff
    style AdvanceEngine fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#fff
    style SettlementRouter fill:#ef4444,stroke:#dc2626,stroke-width:2px,color:#fff
    style Reputation fill:#06b6d4,stroke:#0891b2,stroke-width:2px,color:#fff
    style DemoUSDC fill:#6b7280,stroke:#4b5563,stroke-width:2px,color:#fff

Invoice Lifecycle Flow

sequenceDiagram
    participant Seller
    participant InvoiceRegistry
    participant InvoiceNFT
    participant AdvanceEngine
    participant Vault
    participant Buyer
    participant SettlementRouter
    participant Reputation

    Note over Seller,Reputation: 1. CREATE INVOICE
    Seller->>InvoiceRegistry: createInvoice(buyer, amount, dueDate)
    InvoiceRegistry->>InvoiceNFT: mintInvoiceNFT(invoiceId, seller)
    InvoiceNFT-->>Seller: ERC721 NFT
    InvoiceRegistry-->>Seller: Invoice Created (Status: Issued)

    Note over Seller,Reputation: 2. [OPTIONAL] REQUEST ADVANCE
    Seller->>AdvanceEngine: requestAdvance(invoiceId, ltv, apr)
    AdvanceEngine->>InvoiceRegistry: getInvoice(invoiceId)
    AdvanceEngine->>InvoiceNFT: Verify ownership
    AdvanceEngine->>Vault: borrow(advanceAmount)
    Vault-->>AdvanceEngine: USDC
    AdvanceEngine->>InvoiceRegistry: markFinanced(invoiceId)
    AdvanceEngine-->>Seller: USDC (70-80% LTV)
    InvoiceRegistry-->>Seller: Status: Financed

    Note over Seller,Reputation: 3. PAY INVOICE
    Buyer->>SettlementRouter: payInvoice(invoiceId)
    SettlementRouter->>Buyer: Transfer USDC
    SettlementRouter->>InvoiceRegistry: updateStatus(Paid)
    
    Note over SettlementRouter: Settlement Waterfall (Atomic)
    SettlementRouter->>SettlementRouter: Calculate Fee (0.5%)
    SettlementRouter->>Treasury: Protocol Fee
    alt Invoice was Financed
        SettlementRouter->>AdvanceEngine: getRepaymentAmount()
        AdvanceEngine-->>SettlementRouter: repayment + interest
        SettlementRouter->>Vault: repay(amount)
    end
    SettlementRouter->>Seller: Remainder USDC
    SettlementRouter->>InvoiceRegistry: updateStatus(Cleared)
    SettlementRouter->>Reputation: updateReputation(seller, amount)
    
    Note over Seller,Reputation: 4. REPUTATION IMPROVES
    Reputation-->>Seller: Better Terms Unlocked<br/>(Higher LTV, Lower APR)

Liquidity Provider Flow

flowchart LR
    Start([LP Starts]) --> Deposit[Deposit USDC<br/>to Vault]
    Deposit --> Receive[Receive USMT+<br/>1:1 Receipt Token]
    
    Receive --> Choice{Stake?}
    Choice -->|Yes| Stake[Stake USMT+]
    Choice -->|No| Hold[Hold USMT+<br/>Liquid Position]
    
    Stake --> ReceiveStake[Receive sUSMT+<br/>Staked Token]
    ReceiveStake --> Earn[Earn 15-25% APY<br/>From Borrower Repayments]
    
    Hold --> EarnSimple[Earn from<br/>Vault Utilization]
    
    Earn --> WithdrawStake[Unstake sUSMT+]
    EarnSimple --> Withdraw[Withdraw USDC]
    WithdrawStake --> Withdraw
    
    Withdraw --> Burn[Burn USMT+<br/>Receive USDC]
    Burn --> End([Exit])
    
    style Start fill:#6b7280,stroke:#4b5563,stroke-width:2px,color:#fff
    style Deposit fill:#10b981,stroke:#059669,stroke-width:2px,color:#fff
    style Receive fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#fff
    style Choice fill:#6366f1,stroke:#4f46e5,stroke-width:2px,color:#fff
    style Stake fill:#06b6d4,stroke:#0891b2,stroke-width:2px,color:#fff
    style Hold fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#fff
    style ReceiveStake fill:#06b6d4,stroke:#0891b2,stroke-width:2px,color:#fff
    style Earn fill:#ef4444,stroke:#dc2626,stroke-width:2px,color:#fff
    style EarnSimple fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#fff
    style WithdrawStake fill:#6366f1,stroke:#4f46e5,stroke-width:2px,color:#fff
    style Withdraw fill:#2563eb,stroke:#1e40af,stroke-width:2px,color:#fff
    style Burn fill:#10b981,stroke:#059669,stroke-width:2px,color:#fff
    style End fill:#6b7280,stroke:#4b5563,stroke-width:2px,color:#fff

Settlement Waterfall

flowchart TD
    Payment[Buyer Pays Invoice<br/>100% Invoice Amount] --> Settlement[SettlementRouter]
    
    Settlement --> CalcFee[Calculate Protocol Fee<br/>0.5%]
    CalcFee --> Fee[Protocol Fee<br/>→ Treasury]
    
    Settlement --> Check{Invoice<br/>Financed?}
    Check -->|Yes| CalcRepay[Calculate Repayment<br/>Principal + Interest]
    Check -->|No| NoRepay[No Repayment<br/>0 USDC]
    
    CalcRepay --> Repay[Repayment<br/>→ Vault]
    NoRepay --> CalcRemainder
    
    Fee --> CalcRemainder[Calculate Seller Remainder<br/>Invoice - Fee - Repayment]
    Repay --> CalcRemainder
    
    CalcRemainder --> Remainder[Seller Remainder<br/>→ Seller]
    
    Settlement --> UpdateStatus[Update Invoice Status<br/>Paid → Cleared]
    Settlement --> UpdateRep[Update Reputation<br/>Score + Tier]
    
    style Payment fill:#2563eb,stroke:#1e40af,stroke-width:2px,color:#fff
    style Settlement fill:#ef4444,stroke:#dc2626,stroke-width:2px,color:#fff
    style CalcFee fill:#6366f1,stroke:#4f46e5,stroke-width:2px,color:#fff
    style Fee fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#fff
    style Check fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#fff
    style CalcRepay fill:#06b6d4,stroke:#0891b2,stroke-width:2px,color:#fff
    style NoRepay fill:#6b7280,stroke:#4b5563,stroke-width:2px,color:#fff
    style Repay fill:#10b981,stroke:#059669,stroke-width:2px,color:#fff
    style CalcRemainder fill:#6366f1,stroke:#4f46e5,stroke-width:2px,color:#fff
    style Remainder fill:#06b6d4,stroke:#0891b2,stroke-width:2px,color:#fff
    style UpdateStatus fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#fff
    style UpdateRep fill:#10b981,stroke:#059669,stroke-width:2px,color:#fff

##Quick Start

Installation

# 1. Clone the repository
git clone https://github.com/Adityaakr/SETTL..git
cd SETTL.

# 2. Install dependencies
npm install

# 3. Set up environment variables
cp .env.example .env  # Create .env file and fill in your values

# 4. Start development server
npm run dev

The development server will start on http://localhost:8080

📋 Detailed Setup Instructions

Step 1: Clone Repository

git clone https://github.com/Adityaakr/SETTL..git
cd SETTL.

Step 2: Install Dependencies

npm install

This installs:

Frontend dependencies (React, Vite, TypeScript, Wagmi, etc.)
Smart contract dependencies (Hardhat, Ethers.js, OpenZeppelin)
All required packages listed in package.json

Step 3: Environment Configuration

Create a .env file in the root directory by copying .env.example:

cp .env.example .env

Then fill in your environment variables. See .env.example for all required variables.

Required Environment Variables:

VITE_PRIVY_APP_ID - Get from Privy Dashboard
VITE_MANTLE_CHAIN_ID - Set to 5003 for Mantle Sepolia
DEPLOYER_PRIVATE_KEY - Your wallet private key for deploying contracts
VITE_RECLAIM_APP_ID - (Optional) For zkTLS proofs via Reclaim Protocol

Contract addresses will be populated after deployment.

Important: Never commit your .env file to version control. It's already included in .gitignore.

Step 4: Get Testnet ETH

To deploy contracts and interact with the protocol, you need Mantle Sepolia testnet ETH:

Get testnet ETH from Mantle Faucet
Add Mantle Sepolia network to your wallet:
- Network Name: Mantle Sepolia
- RPC URL: https://rpc.sepolia.mantle.xyz
- Chain ID: 5003
- Currency Symbol: ETH
- Block Explorer: https://explorer.testnet.mantle.xyz

🏗️ Smart Contract Deployment

Deploy All Contracts

Deploy all smart contracts to Mantle Sepolia testnet:

# Compile contracts first (optional, deploy script will compile)
npm run compile

# Deploy all contracts
npm run deploy

What gets deployed:

DemoUSDC - Demo USDC token for testing
InvoiceNFT - ERC721 NFT contract for tokenized invoices
InvoiceRegistry - Invoice creation and state management
Vault - Liquidity pool for invoice financing
AdvanceEngine - Instant financing engine
Reputation - On-chain credit scoring system
SettlementRouter - Automated payment settlement
USMTPlus - Receipt token for vault deposits
Staking - Staking contract for sUSMT+ tokens

Deployment Output:

The script will:

Deploy all contracts in the correct order
Configure roles and permissions between contracts
Save contract addresses to contracts.json
Display environment variables to add to .env

Example Output:

✅ Deployment complete!

Contract addresses saved to: contracts.json

VITE_INVOICE_NFT_ADDRESS=0x...
VITE_INVOICE_REGISTRY_ADDRESS=0x...
VITE_VAULT_ADDRESS=0x...
VITE_ADVANCE_ENGINE_ADDRESS=0x...
VITE_REPUTATION_ADDRESS=0x...
VITE_SETTLEMENT_ROUTER_ADDRESS=0x...

Copy these addresses to your .env file.

Verify Contracts (Optional)

After deployment, verify contracts on Mantle Explorer:

# Set your Mantle Etherscan API key in .env
MANTLE_ETHERSCAN_API_KEY=your_api_key

# Verify contracts
npm run verify

This requires:

Mantle Etherscan API key (get from Mantle Explorer)
Contracts to be fully confirmed on-chain

Manual Deployment (Advanced)

For more control, deploy contracts individually:

# Using Hardhat console
npx hardhat console --network mantleSepolia

# Or create custom deployment script
# See scripts/deploy-all.ts for reference

🎨 Frontend Deployment

Development Mode

npm run dev

Starts Vite dev server with hot reload on http://localhost:8080

Production Build

# Build for production
npm run build

# Preview production build locally
npm run preview

### Testing the Complete Flow

1. **Deploy Contracts:**
   ```bash
   npm run deploy

Start Frontend:
```
npm run dev
```
Fund Wallets:
- Use Settings → Demo Setup to mint DemoUSDC
- Fund test wallets with DemoUSDC
Test Invoice Flow:
- Create invoice as Seller
- Request advance (optional)
- Pay invoice as Buyer
- Verify settlement waterfall

📚 Architecture Overview

Smart Contracts

InvoiceRegistry
    ├── Creates invoices
    └── Mints InvoiceNFT (ERC721)

InvoiceNFT
    └── Represents tokenized invoices

Vault
    ├── Accepts LP deposits (USDC)
    ├── Mints USMT+ (1:1 receipt token)
    └── Provides liquidity for advances

Staking
    ├── Accepts USMT+ deposits
    ├── Mints sUSMT+ (staked receipt token)
    └── Targets 15-25% APY yield

AdvanceEngine
    ├── Uses InvoiceNFT as collateral
    └── Borrows from Vault

SettlementRouter
    ├── Handles invoice payments
    ├── Executes settlement waterfall:
    │   ├── Protocol fee (0.5%)
    │   ├── Vault repayment (if financed)
    │   └── Seller remainder
    └── Updates Reputation

Reputation
    └── Tracks on-chain credit scores

Frontend Architecture

React + TypeScript
    ├── Privy (Embedded Wallets)
    ├── Wagmi (Web3 Interactions)
    └── Reclaim Protocol (zkTLS proofs - optional)

🔐 Security Considerations

For Users

Non-Custodial: SETTL does not hold user funds; all transactions are on-chain
Smart Contracts: All contracts use OpenZeppelin libraries and best practices
Audits: Contracts should be audited before mainnet deployment
Testnet Only: Current deployment is on Mantle Sepolia testnet

For Developers

Private Keys: Never commit private keys to version control
Environment Variables: Keep .env secure and never share it
Contract Upgrades: Current contracts are not upgradeable (immutable)
Access Control: Uses OpenZeppelin's AccessControl for role-based permissions

🤝 Contributing

SETTL is currently in active development. For contributions:

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

📄 License

🌐 Learn More

Introduction: See INTRO.md for project overview and pitch
Contact: Telegram @Adityaakrx | Twitter @adityakrx

Name		Name	Last commit message	Last commit date
Latest commit History 201 Commits
contracts		contracts
public		public
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
.npmrc		.npmrc
INTRO.md		INTRO.md
README.md		README.md
bun.lockb		bun.lockb
components.json		components.json
eslint.config.js		eslint.config.js
hardhat.config.cjs		hardhat.config.cjs
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.ts		tailwind.config.ts
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vercel.json		vercel.json
vite.config.ts		vite.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

SETTL.

🏗️ Architecture

System Overview

Invoice Lifecycle Flow

Liquidity Provider Flow

Settlement Waterfall

Installation

📋 Detailed Setup Instructions

Step 1: Clone Repository

Step 2: Install Dependencies

Step 3: Environment Configuration

Step 4: Get Testnet ETH

🏗️ Smart Contract Deployment

Deploy All Contracts

Verify Contracts (Optional)

Manual Deployment (Advanced)

🎨 Frontend Deployment

Development Mode

Production Build

📚 Architecture Overview

Smart Contracts

Frontend Architecture

🔐 Security Considerations

For Users

For Developers

🤝 Contributing

📄 License

🌐 Learn More

About

Uh oh!

Releases

Packages

Languages

Adityaakr/SETTL.

Folders and files

Latest commit

History

Repository files navigation

SETTL.

🏗️ Architecture

System Overview

Invoice Lifecycle Flow

Liquidity Provider Flow

Settlement Waterfall

Installation

📋 Detailed Setup Instructions

Step 1: Clone Repository

Step 2: Install Dependencies

Step 3: Environment Configuration

Step 4: Get Testnet ETH

🏗️ Smart Contract Deployment

Deploy All Contracts

Verify Contracts (Optional)

Manual Deployment (Advanced)

🎨 Frontend Deployment

Development Mode

Production Build

📚 Architecture Overview

Smart Contracts

Frontend Architecture

🔐 Security Considerations

For Users

For Developers

🤝 Contributing

📄 License

🌐 Learn More

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages