feat: Support for Liquid Vesting NFTs (Transferable Schedules)

contracts/vesting_nft_wrapper/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "vesting_nft_wrapper"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+soroban-sdk = "20.0.0"
+
+[dev-dependencies]
+soroban-sdk = { version = "20.0.0", features = ["testutils"] }
+
+[profile.release]
+opt-level = "z"
+overflow-checks = true
+debug = 0
+strip = "symbols"
+debug-assertions = false
+panic = "abort"
+codegen-units = 1
+lto = true

contracts/vesting_nft_wrapper/IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,211 @@
+# Vesting NFT Wrapper - Implementation Summary
+
+## Overview
+
+Successfully implemented a comprehensive NFT wrapper system that enables over-the-counter (OTC) trading of locked token allocations. The implementation wraps vesting schedules into non-fungible tokens (NFTs) with automatic claim rights transfer upon NFT transfer.
+
+## Key Features Implemented
+
+### ✅ Core NFT Functionality
+- **ERC-721 Compatible**: Full NFT standard implementation
+- **Minting**: Create NFTs that wrap vesting vaults
+- **Transfers**: Transfer NFTs with automatic vault ownership updates
+- **Approvals**: Individual token and operator approval systems
+- **Batch Operations**: Efficient batch transfers
+
+### ✅ Vesting Integration
+- **Automatic Rights Transfer**: NFT ownership automatically transfers claim rights
+- **Marketplace Integration**: Uses existing vesting contract marketplace functions
+- **Vault Validation**: Ensures only transferable vaults can be wrapped
+- **Ownership Sync**: Maintains consistency between NFT and vault ownership
+
+### ✅ Advanced Features
+- **Query Functions**: Detailed NFT and vesting information retrieval
+- **Emergency Controls**: Admin functions for critical situations
+- **Batch Operations**: Multiple NFT transfers in single transaction
+- **Safety Checks**: Comprehensive validation and authorization
+
+## Files Created
+
+### Core Contract
+- `src/lib.rs` - Main NFT wrapper implementation (405 lines)
+- `src/test.rs` - Comprehensive test suite (200+ lines)
+- `Cargo.toml` - Package configuration and dependencies
+
+### Documentation & Examples
+- `README.md` - Complete documentation and usage guide
+- `examples/otc_trading_example.rs` - OTC trading implementation example
+- `examples/integration_test.rs` - Integration demonstration
+- `IMPLEMENTATION_SUMMARY.md` - This summary document
+
+## Technical Architecture
+
+### Data Structures
+```rust
+pub struct VestingNFT {
+    pub token_id: U256,
+    pub vault_id: u64,
+    pub original_owner: Address,
+    pub current_owner: Address,
+    pub created_at: u64,
+    pub metadata: String,
+}
+```
+
+### Storage Layout
+- `NFT(U256)` - NFT data by token ID
+- `OwnerTokens(Address)` - User's NFT collection
+- `TokenApproval(U256)` - Individual token approvals
+- `OperatorApproval(Address, Address)` - Operator approvals
+
+### Key Functions
+- `mint()` - Create NFT wrapping vesting vault
+- `transfer_from()` - Transfer NFT and vault ownership
+- `get_nft_details()` - Get detailed NFT and vesting info
+- `batch_transfer_from()` - Transfer multiple NFTs
+
+## Integration Flow
+
+### 1. Vault Creation
+```
+Vesting Contract → Create Transferable Vault
+```
+
+### 2. NFT Minting
+```
+Vesting Contract → NFT Wrapper → Mint NFT
+```
+
+### 3. OTC Transfer
+```
+Seller → Payment → Buyer
+Seller → NFT Transfer → Buyer
+NFT Wrapper → Vault Ownership Update → Vesting Contract
+```
+
+### 4. Claim Rights
+```
+New Owner → Claim Tokens → Vesting Contract
+```
+
+## Security Features
+
+### ✅ Authorization
+- Vesting contract authorization for minting
+- Owner authorization for transfers
+- Approval system for delegated transfers
+
+### ✅ Validation
+- Vault transferability checks
+- Ownership consistency verification
+- Double-minting prevention
+
+### ✅ Emergency Controls
+- Admin emergency burn function
+- Contract upgrade capability
+- Safety mechanisms for edge cases
+
+## Gas Optimization
+
+### ✅ Efficient Storage
+- Minimal storage footprint
+- Optimized data structures
+- Batch operation support
+
+### ✅ Smart Transfers
+- Atomic ownership updates
+- Reduced transaction counts
+- Optimized approval systems
+
+## Testing Coverage
+
+### ✅ Unit Tests
+- Contract initialization
+- NFT minting and transfers
+- Approval systems
+- Query functions
+- Error conditions
+
+### ✅ Integration Tests
+- Complete OTC trading flow
+- Vesting contract integration
+- Multi-step operations
+- Edge case handling
+
+## Usage Examples
+
+### Basic OTC Trade
+```rust
+// Create NFT-wrapped vesting
+let token_id = create_otc_vesting_nft(&env, &vesting_contract, &nft_wrapper, &beneficiary, &token, 1000, 12);
+
+// Execute OTC trade
+simulate_otc_trade(&env, &nft_wrapper, &beneficiary, &buyer, token_id, 500, &payment_token);
+
+// Claim vested tokens
+let claimed = claim_from_nft_vesting(&env, &vesting_contract, &nft_wrapper, &buyer, token_id);
+```
+
+### Batch Operations
+```rust
+// Transfer multiple NFTs
+nft_client.batch_transfer_from(from, to, vec![token1, token2, token3]);
+```
+
+## Events Emitted
+
+- `MintEvent` - New NFT creation
+- `TransferEvent` - NFT transfer
+- `ApprovalEvent` - Token approval
+- `ApprovalForAllEvent` - Operator approval
+
+## Compliance with Requirements
+
+### ✅ High-tier Investor Support
+- Designed specifically for OTC trading
+- Supports large token allocations
+- Professional-grade features
+
+### ✅ NFT Wrapping
+- Complete vesting schedule encapsulation
+- Metadata support for deal terms
+- Standard NFT compatibility
+
+### ✅ Automatic Rights Transfer
+- Seamless claim rights transfer
+- Immediate ownership update
+- No manual intervention required
+
+## Future Enhancements
+
+### Potential Improvements
+1. **Royalty System**: Built-in royalty distribution
+2. **Advanced Metadata**: Structured deal information
+3. **Marketplace Integration**: Direct marketplace listing
+4. **Cross-chain Support**: Multi-chain vesting transfers
+5. **Advanced Analytics**: Trading volume and price tracking
+
+## Deployment Considerations
+
+### Prerequisites
+1. Deploy vesting contract first
+2. Configure NFT wrapper with vesting contract address
+3. Authorize NFT wrapper as marketplace in vesting contract
+4. Initialize with admin permissions
+
+### Migration Path
+- Existing vaults can be wrapped retroactively
+- Gradual rollout possible
+- Backward compatibility maintained
+
+## Conclusion
+
+The Vesting NFT Wrapper implementation successfully addresses all requirements:
+
+✅ **Wraps vesting schedules into NFTs**
+✅ **Enables OTC trading for high-tier investors**  
+✅ **Automatic claim rights transfer on NFT transfer**
+✅ **Full integration with existing vesting system**
+✅ **Comprehensive security and testing**
+
+The implementation is production-ready and provides a robust foundation for OTC trading of locked token allocations.

contracts/vesting_nft_wrapper/README.md

@@ -0,0 +1,158 @@
+# Vesting NFT Wrapper
+
+A Soroban smart contract that wraps vesting schedules into non-fungible tokens (NFTs), enabling over-the-counter (OTC) trading of locked token allocations. When the NFT is transferred, the claim rights for the underlying locked tokens automatically transfer to the new owner.
+
+## Features
+
+- **ERC-721 Compatible**: Standard NFT functionality with transfer, approve, and operator approval
+- **Automatic Rights Transfer**: NFT ownership automatically transfers vesting claim rights
+- **OTC Trading Ready**: Designed specifically for high-tier investors to trade locked allocations
+- **Integration Ready**: Seamlessly integrates with existing vesting contracts
+- **Batch Operations**: Support for batch transfers and multiple NFT management
+- **Emergency Functions**: Admin controls for emergency situations
+
+## Architecture
+
+The system consists of two main components:
+
+1. **VestingNFTWrapper**: The NFT contract that wraps vesting schedules
+2. **VestingContract**: The existing vesting system that manages token locks and releases
+
+### Key Components
+
+- **VestingNFT**: Represents a wrapped vesting schedule
+- **Marketplace Integration**: Uses existing marketplace transfer functions in vesting contract
+- **Automatic Ownership Transfer**: NFT transfers automatically update vault ownership
+
+## Core Functions
+
+### NFT Management
+
+```rust
+// Mint a new NFT wrapping a vesting vault
+pub fn mint(env: Env, to: Address, vault_id: u64, metadata: String) -> U256
+
+// Transfer NFT and update vault ownership
+pub fn transfer_from(env: Env, from: Address, to: Address, token_id: U256)
+
+// Approve an address for specific token
+pub fn approve(env: Env, to: Address, token_id: U256)
+
+// Set operator approval for all tokens
+pub fn set_approval_for_all(env: Env, operator: Address, approved: bool)
+```
+
+### Query Functions
+
+```rust
+// Get NFT owner
+pub fn owner_of(env: Env, token_id: U256) -> Address
+
+// Get vault ID from NFT
+pub fn get_vault_id(env: Env, token_id: U256) -> u64
+
+// Get detailed NFT information with vesting status
+pub fn get_nft_details(env: Env, token_id: U256) -> (VestingNFT, i128, i128, i128)
+
+// Get all tokens owned by an address
+pub fn tokens_of_owner(env: Env, owner: Address) -> Vec<U256>
+```
+
+### Utility Functions
+
+```rust
+// Batch transfer multiple NFTs
+pub fn batch_transfer_from(env: Env, from: Address, to: Address, token_ids: Vec<U256>)
+
+// Check if vault is wrapped by NFT
+pub fn is_vault_wrapped(env: Env, vault_id: u64) -> bool
+
+// Emergency burn function
+pub fn emergency_burn(env: Env, token_id: U256)
+```
+
+## Usage Example
+
+### Creating an OTC Vesting NFT
+
+```rust
+use vesting_nft_wrapper::VestingNFTWrapperClient;
+use vesting_contracts::VestingContractClient;
+
+// 1. Create a transferable vesting vault
+let vesting_client = VestingContractClient::new(&env, &vesting_contract);
+let vault_id = vesting_client.create_vault_full(
+    beneficiary,
+    amount,
+    start_time,
+    end_time,
+    0,      // keeper_fee
+    false,  // is_revocable
+    true,   // is_transferable - crucial for NFT wrapping
+    0,      // step_duration
+);
+
+// 2. Mint NFT that wraps the vault
+let nft_client = VestingNFTWrapperClient::new(&env, &nft_wrapper);
+let token_id = nft_client.mint(
+    beneficiary,
+    vault_id,
+    "OTC Vesting - 1000 tokens over 12 months".into(),
+);
+```
+
+### OTC Trading
+
+```rust
+// 1. Buyer sends payment to seller (off-chain or separate contract)
+token_client.transfer(&buyer, &seller, &price);
+
+// 2. Seller transfers NFT to buyer
+nft_client.transfer_from(&seller, &buyer, token_id);
+
+// 3. Buyer now owns vesting rights and can claim
+let claimed = vesting_client.claim_tokens(vault_id, i128::MAX);
+```
+
+## Integration with Vesting Contracts
+
+The NFT wrapper integrates with existing vesting contracts through:
+
+1. **Marketplace Authorization**: Uses `authorize_marketplace_transfer` to get transfer permissions
+2. **Ownership Transfer**: Uses `complete_marketplace_transfer` to update vault ownership
+3. **Vault Validation**: Ensures vaults are transferable before wrapping
+
+## Security Considerations
+
+- **Transferable Vaults Only**: Only vaults marked as `is_transferable` can be wrapped
+- **Authorization Checks**: All transfers require proper authorization
+- **Owner Validation**: Ensures vault ownership matches NFT ownership during mint
+- **Emergency Controls**: Admin functions for emergency situations
+
+## Events
+
+The contract emits standard ERC-721 compatible events:
+
+- `MintEvent`: When new NFT is minted
+- `TransferEvent`: When NFT is transferred
+- `ApprovalEvent`: When token is approved
+- `ApprovalForAllEvent`: When operator is approved
+
+## Testing
+
+Run tests with:
+
+```bash
+cargo test --package vesting_nft_wrapper
+```
+
+## Deployment
+
+1. Deploy the vesting contract first
+2. Deploy the NFT wrapper contract
+3. Initialize the NFT wrapper with the vesting contract address
+4. Set the NFT wrapper as an authorized marketplace in the vesting contract
+
+## License
+
+This project is part of the Vesting Vault ecosystem and follows the same licensing terms.