Cross-Chain V3 Position Transfer

Note: This repository currently contains the main script files only. The full end-to-end integration, including local POC testing support and AggSandbox integration, will be added soon.

Overview

This educational example shows how to move a Uniswap V3 position from Sepolia to SushiSwap V3 on Tatara (Katana testnet) using Agglayer's Unified Bridge, while preserving the economic characteristics and adding staking rewards.

Learning Objectives

Concept	What You'll Learn	Real-World Application
Concentrated Liquidity	How V3 positions work with tick ranges	Advanced DeFi position management
Cross-Chain Bridging	Message + asset bridging patterns	Multi-chain protocol integration
Position Decomposition	Breaking down LP positions into components	DeFi composability principles
Automated Execution	Smart contract choreography	Protocol automation design

---

Table of Contents

1. Understanding V3 Positions
2. Position Decomposition Logic
3. Cross-Chain Message Design
4. Destination Recreation Logic
5. Enhanced Staking Integration
6. File Structure and Responsibilities
7. Key Implementation Patterns
8. Educational Code Examples

---

1. Understanding V3 Positions

1.1 What Makes V3 Special

Traditional V2 vs Concentrated V3:

V2 Liquidity (Full Range)
├── Provides liquidity from 0 to infinity
├── Lower capital efficiency
└── Uniform fee earning across all prices

V3 Liquidity (Concentrated)
├── Provides liquidity within specific price range
├── Higher capital efficiency (can be 1000x+)
└── Only earns fees when price is in range

1.2 V3 Position Anatomy

A V3 position consists of:

Component	Description	Example
Token Pair	Two tokens being provided	ETH/USDC
Fee Tier	Trading fee percentage	0.3% (3000 basis points)
Tick Range	Price bounds for liquidity	Lower: -276324, Upper: 276324
Liquidity Amount	Actual liquidity provided	1000000000000000000
Accumulated Fees	Uncollected trading fees	0.1 ETH + 150 USDC

1.3 The Tick System

Understanding Ticks:

• Each tick represents a 0.01% price change (1.0001^tick)
• Positions are defined by two ticks (lower and upper bounds)
• Different fee tiers have different tick spacings
• Current price determines if position is earning fees

---

2. Position Decomposition Logic

2.1 The Unwinding Process

File: scripts/v3/positionAnalyzer.js

Core Concept: Before bridging, we must "unwind" the V3 position back into its constituent tokens.

Step-by-Step Breakdown:

Original V3 Position
    │
    ├── Position has liquidity locked in price range
    ├── May have accumulated uncollected fees
    └── Exists as an NFT with specific parameters
    │
Unwinding Process
    │
    ├── 1. Read Position Metadata
    │   ├── Extract token addresses, fee tier
    │   ├── Get tick range (lower/upper bounds)
    │   └── Read liquidity amount
    │
    ├── 2. Calculate Token Amounts
    │   ├── Use current pool price
    │   ├── Apply V3 math to convert liquidity → tokens
    │   └── Handle in-range vs out-of-range scenarios
    │
    ├── 3. Collect All Fees
    │   ├── Call collect() with maximum parameters
    │   ├── Receive any accumulated trading fees
    │   └── Add to total token amounts
    │
    └── 4. Remove Liquidity
        ├── Call decreaseLiquidity() to remove 100%
        ├── Receive underlying token amounts
        └── Now have discrete token balances

2.2 Mathematical Foundations

File: utils/v3Calculator.js

Key Insight: V3 uses mathematical formulas to convert between liquidity and token amounts based on current price.

Price-Based Calculations:

• If current price is below range: Only Token0 (lower-priced token)
• If current price is in range: Both Token0 and Token1
• If current price is above range: Only Token1 (higher-priced token)

---

3. Cross-Chain Message Design

3.1 The Bridge & Call Pattern

File: services/v3BridgeService.js

Educational Concept: Instead of just bridging tokens, we bridge tokens + instructions for what to do with them.

Message Structure:

Bridge Message Components
    │
    ├── Asset Component
    │   ├── TokenA amount (from unwound position)
    │   ├── TokenB amount (from unwound position)  
    │   └── Destination address (recreation contract)
    │
    └── Instruction Component
        ├── Function to call: "recreateV3Position"
        ├── Original position parameters
        ├── Tick range to recreate
        └── Staking preferences

3.2 Calldata Encoding Strategy

File: utils/v3CallDataEncoder.js

Purpose: Convert the recreation instructions into bytecode that can be executed on the destination chain.

Encoding Process:

Position Parameters → ABI Encoding → Bytecode → Bridge Payload
    │
    ├── Take original tick bounds
    ├── Calculate token amounts (including fees)
    ├── Set recreation parameters
    └── Encode as contract function call

Why This Works: The bridge can execute arbitrary smart contract functions on the destination chain, allowing complex position recreation.

---

4. Destination Recreation Logic

4.1 Pool Management Strategy

File: services/poolManager.js

Educational Focus: Understanding how to ensure the destination chain is ready for position recreation.

Pool Preparation Logic:

Destination Chain Readiness
    │
    ├── 1. Check Pool Existence
    │   ├── Does TokenA/TokenB pool exist?
    │   ├── Is the fee tier (0.3%) available?
    │   └── If not, can we create it?
    │
    ├── 2. Price Initialization
    │   ├── If new pool, what's the starting price?
    │   ├── Use 1:1 ratio or market-based pricing
    │   └── Initialize pool with sqrtPriceX96
    │
    └── 3. Position Recreation
        ├── Mint new V3 NFT with same parameters
        ├── Use received tokens as liquidity
        └── Transfer NFT to original user

4.2 Position Recreation Flow

Educational Insight: The destination chain receives both tokens and execution instructions simultaneously.

Recreation Sequence:

1. Token Reception: Bridge delivers TokenA + TokenB to smart contract
2. Pool Verification: Ensure the target pool exists and is initialized
3. Position Minting: Call PositionManager.mint() with original parameters
4. NFT Transfer: Send new position NFT to the user
5. Staking Activation: Automatically stake position for enhanced rewards

---

5. Enhanced Staking Integration

5.1 Staking as Value Addition

File: services/stakingIntegration.js

Educational Concept: Cross-chain migration can improve the original position by adding new yield opportunities.

Value Enhancement Strategy:

Original Position (Sepolia)
    │
    ├── Earns trading fees from Uniswap V3
    ├── No additional rewards
    └── Single yield source
    │
Enhanced Position (Tatara)
    │
    ├── Earns trading fees from SushiSwap V3
    ├── Additional SUSHI token rewards from staking
    ├── Potential boost multipliers
    └── Multiple yield sources

5.2 Reward Mechanics

Staking Integration Benefits:

• Base Yield: Same trading fee earnings as original position
• Bonus Yield: Additional rewards from SushiSwap staking program
• Multipliers: Longer staking commitments earn higher rewards
• Compounding: Rewards can be reinvested into the position

---

6. File Structure and Responsibilities

6.1 Core Analysis Files

File	Purpose	Key Learning
positionAnalyzer.js	Extract V3 position data	How to read on-chain position state
v3Calculator.js	Mathematical conversions	V3 liquidity ↔ token amount math
feeCollector.js	Systematic fee extraction	Maximizing position value before transfer

6.2 Bridge Integration Files

File	Purpose	Key Learning
v3BridgeService.js	End-to-end orchestration	Complex multi-step process coordination
v3CallDataEncoder.js	Function call encoding	How to embed instructions in bridge messages
poolManager.js	Destination preparation	Ensuring target chain readiness

6.3 Enhancement Files

File	Purpose	Key Learning
stakingIntegration.js	Yield optimization	Adding value through cross-chain migration
bridgeConfig.js	Network configuration	Multi-chain protocol coordination

---

7. Key Implementation Patterns

7.1 The Decompose-Bridge-Recompose Pattern

Universal Principle: Any complex DeFi position can be migrated using this pattern:

1. DECOMPOSE
   ├── Analyze complex position
   ├── Break into constituent parts
   └── Extract maximum value

2. BRIDGE  
   ├── Transfer parts + instructions
   ├── Use bridge's execution capabilities
   └── Maintain atomicity

3. RECOMPOSE
   ├── Recreate position on destination
   ├── Add enhancements if possible
   └── Return control to user

7.2 The State Preservation Pattern

Key Insight: Successful cross-chain migration preserves economic intent while allowing for enhancements.

What Gets Preserved:

• Economic exposure (same token pair, similar price range)
• Capital efficiency (same concentration level)
• Earning potential (fees + additional rewards)

What Gets Enhanced:

• Additional yield sources (staking rewards)
• Better protocol features (if available)
• Improved capital efficiency (if possible)

---

This educational walkthrough demonstrates how complex DeFi positions can be migrated across chains while preserving their economic characteristics and potentially adding new value through enhanced protocols. The key insight is that any position can be decomposed into its parts, bridged with reconstruction instructions, and recomposed on the destination with enhancements.