# Overview

**RealSafe** is a comprehensive liquidity locking protocol for decentralized exchanges, supporting Uniswap V2 LP tokens and V3 NFT positions. Built with security and flexibility in mind, RealSafe enables projects to lock their liquidity with time-based or conditional unlock mechanisms.

## What is RealSafe?

RealSafe provides trustless liquidity locking infrastructure for DeFi protocols, particularly DEX liquidity providers. It ensures that liquidity cannot be removed before a specified time, providing confidence to token holders and preventing rug pulls.

### Key Features

#### Multi-Protocol Support

* **V2 Locker**: Lock ERC-20 LP tokens from Uniswap V2
* **V3 Locker**: Lock NFT positions from Uniswap V3 with concentrated liquidity
* **Universal Compatibility**: Works across multiple EVM chains (Monad, with more coming soon)

#### Flexible Unlock Mechanisms

* **Time-Based Locks**: Set specific unlock dates (up to 10 years)
* **Conditional Locks**: Custom unlock logic via condition contracts
* **Extendable Locks**: Owners can extend lock duration anytime
* **2-Step Ownership Transfer**: Secure lock ownership transfers

#### Fee Collection

* **V3 Fee Collection**: Collect trading fees while position is locked (V3 only)
* **V2 Fee Accrual**: Trading fees automatically increase LP token value (V2)
* **Creation Fees**: Flat native token fee for creating locks
* **Claim Fees**: Small percentage on claimed V3 fees (1% default)

#### Security Features

* **ReentrancyGuard**: Protection against reentrancy attacks
* **Pausable**: Emergency pause functionality
* **Emergency Withdrawals**: Owner-controlled rescue functions
* **Battle-Tested Patterns**: Based on UNCX locker architecture

## Architecture

### Core Contracts

```
RealSafe System
├── V3Locker.sol               # V3 NFT position locker
├── V2Locker.sol              # V2 LP token locker
└── TimeBasedCondition.sol    # Example condition contract
```

### Lock Lifecycle

```
1. CREATE LOCK
   ├── User approves NFT/LP token
   ├── User calls lockPosition() or lockLP()
   ├── Contract receives tokens
   ├── Lock record created
   └── Event emitted

2. ACTIVE LOCK
   ├── Collect trading fees (V3)
   ├── Extend lock duration
   ├── Transfer ownership
   └── Update collect address

3. UNLOCK
   ├── Check unlock time/conditions
   ├── Mark lock as inactive
   ├── Transfer tokens back to owner
   └── Event emitted
```

## Use Cases

### For Project Teams

* **Liquidity Commitment**: Lock initial liquidity to build trust
* **Vesting Schedules**: Lock team liquidity with gradual unlocks
* **Anti-Rug Protection**: Prove liquidity cannot be removed
* **Marketing Tool**: Show locked liquidity on your website

### For Liquidity Providers

* **V3 Fee Collection**: Collect trading fees while position is locked (V3 only)
* **V2 Fee Accrual**: Trading fees automatically increase your LP token value (V2)
* **Long-Term Positions**: Commit to pools without temptation to exit
* **Governance Participation**: Maintain voting power in LP-based DAOs
* **Risk Management**: Force yourself to HODL through volatility

### For DEX Users

* **Trust Verification**: Check if project liquidity is locked
* **Safety Score**: Higher locked liquidity = safer project
* **Exit Scam Prevention**: Locked liquidity cannot be rugged
* **Community Confidence**: Transparent on-chain verification

## Supported Networks

| Network           | Chain ID | V3 Locker | V2 Locker | Status      |
| ----------------- | -------- | --------- | --------- | ----------- |
| **Monad Testnet** | TBD      | Yes       | Yes       | Testnet     |
| **Monad Mainnet** | TBD      | Planned   | Planned   | Coming Soon |

## Quick Example

### Locking a V3 Position

```solidity
// 1. Approve the NFT
positionManager.approve(v3LockerAddress, tokenId);

// 2. Lock for 90 days
uint256 unlockDate = block.timestamp + 90 days;
v3Locker.lockPosition{value: creationFee}(
    tokenId,
    unlockDate,
    msg.sender,  // collect address
    address(0)   // no condition
);
```

### Locking V2 LP Tokens

```solidity
// 1. Approve LP tokens
lpToken.approve(v2LockerAddress, amount);

// 2. Lock for 1 year
uint256 unlockDate = block.timestamp + 365 days;
v2Locker.lockLP{value: creationFee}(
    lpTokenAddress,
    amount,
    unlockDate,
    false,       // not permanent
    address(0)   // no condition
);
```

## Fee Structure

### Monad Testnet

* **Creation Fee**: 0.0001 MON
* **Claim Fee**: 1% (100 bps)
* **Lock Fee**: 1% (100 bps)

*Note: Mainnet fees will be adjusted based on network economics*

## Benefits

### Security

* Non-custodial (users retain ownership)
* Auditable on-chain state
* Emergency pause mechanism
* Tested against common attack vectors

### Transparency

* All locks visible on-chain
* Real-time verification via subgraph
* Historical lock data preserved
* Event-driven analytics

### Flexibility

* Multiple unlock strategies
* Extendable lock durations
* Transferable ownership
* Configurable fee recipients

### User Experience

* Simple integration
* Clear error messages
* Gas optimized
* Multi-chain support

## Next Steps

* [Quick Start Guide](https://docs.realsafe.app/developer-documentation/quickstart) - Get started in minutes
* [V3 Locker Interface](https://docs.realsafe.app/interfaces/v3) - Complete V3 API reference
* [V2 Locker Interface](https://docs.realsafe.app/interfaces/v2) - Complete V2 API reference
* [Security Guide](https://docs.realsafe.app/reference/security) - Security best practices
* [Deployments](https://docs.realsafe.app/reference/deployments) - Contract addresses across networks
* [Advanced Features](https://docs.realsafe.app/advanced/conditional-unlocks) - Conditional unlocks and more
