Welsh Street Liquidity Engine

Core Liquidity Functions

Welsh Street Exchange implements a unique five-tier liquidity system that addresses different needs within the Welsh economy. Understanding the distinctions between these functions is crucial for grasping how the protocol transforms idle WELSH into productive DeFi infrastructure.

provide-liquidity

Purpose: Normal liquidity provision with LP token issuance Who can use: Anyone can provide liquidity Tracking: Only increases reserves (reserve-a, reserve-b) and mints LP tokens Key difference: This creates “available” liquidity that users can withdraw

(define-public (provide-liquidity (amount-a uint))
  (let (
    (res-a (var-get reserve-a))
    (res-b (var-get reserve-b))
    (lock-a (var-get locked-a))
    (lock-b (var-get locked-b))
    (aval-a (if (>= res-a lock-a) (- res-a lock-a) u0))
    (aval-b (if (>= res-b lock-b) (- res-b lock-b) u0))
    ;; Calculates amount-b based on available liquidity ratio
    ;; Mints LP tokens to user proportional to their contribution
  )
  ;; Updates reserve-a and reserve-b
  ;; Issues CREDIT tokens representing pool share

Key Features:

• LP Tokens Issued: Users receive CREDIT tokens representing their pool share
• Withdrawable: LP tokens can be redeemed via remove-liquidity (subject to withdrawal tax)
• Reward Eligible: LP holders earn trading fees and emission rewards
• Ratio Dependent: Uses existing available liquidity ratio for token-b calculation

lock-liquidity

Purpose: Creates “locked” liquidity that cannot be withdrawn by users Who can use: Only the contract owner can initialize with locked liquidity Tracking: Increases locked-a, locked-b variables Key difference: This liquidity is permanently locked and generates LP tokens that track the lock

(define-public (lock-liquidity (amount-a uint))
  (let (
    (res-a (var-get reserve-a))
    (res-b (var-get reserve-b))
    (amount-b (if (is-eq res-a u0)
      (* amount-a INITIAL_RATIO)
      (/ (* amount-a res-b) res-a)))
    ;; Calculate LP tokens for tracking purposes only
    (amount-lp (sqrti (* amount-a amount-b))) ;; LP calculation for tracking
  )
  (begin
    ;; Transfers tokens to exchange
    (var-set locked-a (+ (var-get locked-a) amount-a))
    (var-set locked-b (+ (var-get locked-b) amount-b))

Key Features:

• No LP Tokens: User receives ZERO LP tokens for their contribution
• Permanent: Cannot be withdrawn by anyone, ever
• Tracking Only: Updates locked-a, locked-b, locked-lp variables for UX/database purposes
• Protocol-Owned: Becomes base liquidity that supports all trading operations
• LP Tracking: The locked-lp variable records how many LP tokens would have been minted but no actual tokens are created

burn-liquidity

Purpose: Voluntarily burn LP tokens to permanently forfeit liquidity claims Behavior: Burns LP tokens without affecting locked liquidity counters - benefits all remaining LP holders

(define-public (burn-liquidity (amount-lp uint))
  (begin
    (asserts! (> amount-lp u0) ERR_ZERO_AMOUNT)
    (try! (contract-call? .credit transfer amount-lp tx-sender .exchange none))
    (try! (as-contract (contract-call? .credit burn amount-lp)))
    ;; Updates user's reward position when LP balance changes
    (try! (contract-call? .rewards update-user-rewards tx-sender))
    ;; Burns LP tokens permanently (reduces total supply)
    ;; Does NOT update locked-a/locked-b counters
    ;; Remaining LP holders get higher value per token
    (ok { burned-lp: amount-lp })

Key Features:

• LP Supply Reduction: Permanently reduces total LP token supply
• No Locked Tracking: Does NOT count toward locked-a/locked-b variables
• Benefits Remaining LPs: Remaining LP holders automatically get higher value per token
• Voluntary Sacrifice: User forfeits their claim to benefit the community

Mathematical Effect:

Before Burn: 1000 LP tokens share 100 WELSH + 10,000 STREET
After 100 LP Burn: 900 LP tokens share 100 WELSH + 10,000 STREET
Result: Each remaining LP token increased in value by ~11%

remove-liquidity

Purpose: Allows users to withdraw their liquidity position at any time Who can use: Any LP token holder can remove all or part of their position Tax Applied: Subject to withdrawal tax that becomes permanently locked liquidity Reward Reset: User’s reward tracking is updated when LP position changes

(define-public (remove-liquidity (amount-lp uint))
  (let (
    ;; Calculate user's share of available liquidity
    (amount-a (/ (* amount-lp aval-a) total-supply-lp))
    (amount-b (/ (* amount-lp aval-b) total-supply-lp))
    ;; Apply withdrawal tax
    (tax-a (/ (* amount-a (var-get tax)) BASIS))
    (tax-b (/ (* amount-b (var-get tax)) BASIS))
    (user-amount-a (- amount-a tax-a))
    (user-amount-b (- amount-b tax-b))
  )
  (begin
    ;; Transfer user's share minus tax
    (try! (transformer .welshcorgicoin user-amount-a tx-sender))
    (try! (transformer .street user-amount-b tx-sender))
    ;; Burn the LP tokens
    (try! (as-contract (contract-call? .credit burn amount-lp)))
    ;; Update user's reward position
    (try! (contract-call? .rewards update-user-rewards tx-sender))
    ;; Tax becomes permanently locked
    (var-set locked-a (+ lock-a tax-a))
    (var-set locked-b (+ lock-b tax-b))

Key Features:

• Partial or Full Withdrawal: Users can remove any amount of their LP tokens
• Withdrawal Tax: Tax percentage is applied (capped at 20% maximum)
• Tax Becomes Locked: Withdrawal taxes permanently increase locked-a and locked-b
• Flexible Timing: Users can withdraw at any time, no lock-up periods
• Reward Position Reset: User’s reward tracking is recalculated based on new LP balance

provide-initial-liquidity

Purpose: Allows contract owner to set initial pool ratio based on market conditions at deployment Who can use: Only contract owner, only when pool is empty Fair Distribution: Creates more equitable LP token economics for community Flexibility: No hardcoded ratios - adapts to market conditions at launch

(define-public (provide-initial-liquidity (amount-a uint) (amount-b uint))
  (let (
    (res-a (var-get reserve-a))
    (res-b (var-get reserve-b))
    (amount-lp (sqrti (* amount-a amount-b))) ;; Geometric mean for first provision
  )
  (begin
    ;; Only works when pool is completely empty
    (asserts! (and (is-eq res-a u0) (is-eq res-b u0)) ERR_ALREADY_INITIALIZED)
    (asserts! (is-eq tx-sender CONTRACT_OWNER) ERR_NOT_CONTRACT_OWNER)
    ;; Mint LP tokens to contract owner (to be burned later)
    (try! (contract-call? .credit mint amount-lp))
    ;; Update owner's reward position
    (try! (contract-call? .rewards update-user-rewards tx-sender))
    ;; Set initial reserves
    (var-set reserve-a amount-a)
    (var-set reserve-b amount-b)

Key Features:

• Fair Distribution Strategy: Owner will slowly burn their LP tokens over time to benefit community
• Geometric Mean LP Allocation: Contract owner receives outsized LP share (standard AMM behavior)
• Governance Flexibility: Owner can respond to market conditions for optimal initial pool setup
• Liquidity Availability: Welsh token availability for seeding may vary based on market conditions
• Market Price Changes: Welsh token market conditions may fluctuate between deployment and initialization
• Market-Based Ratio: Contract owner sets ratio based on actual WELSH market price at deployment
• One-Time Use: Only works when pool is completely empty
• Price Discovery: Enables proper initial price setting based on real market data rather than fixed ratios
• Two Independent Inputs: Takes both amount-a (WELSH) and amount-b (STREET) parameters
• UX Enhancement: Creates more equitable reward distribution for regular users

Fair Distribution Logic:

Traditional AMM Issue: First LP gets massive share via geometric mean
Welsh Street Solution: Owner takes the outsized share, then burns tokens slowly
Result: Community LPs get more fair portion of rewards over time

Mathematical Example:

Owner provides: 1M WELSH + 119M STREET
Owner receives: √(1,000,000 × 119,000,000) = 10,908,712 LP tokens
Subsequent users get proportional shares based on existing reserves
Owner burns LP tokens gradually → Community benefits from increased reward share

Reward System Integration

All liquidity functions that change a user’s LP token balance automatically update their reward position:

;; This line appears in provide-liquidity, remove-liquidity, and burn-liquidity
(try! (contract-call? .rewards update-user-rewards tx-sender))

When Reward Updates Occur:

• ✅ provide-liquidity: User gains LP tokens → reward rate increases
• ✅ provide-initial-liquidity: Owner gains LP tokens → reward position established
• ✅ remove-liquidity: User loses LP tokens → reward rate decreases
• ✅ burn-liquidity: User loses LP tokens → reward rate decreases
• ❌ lock-liquidity: No LP tokens created → no reward impact

Reward Claiming Workflow:

1. Check pending rewards: Use get-reward-user-info to see unclaimed amounts
2. Claim rewards: Call claim-rewards to collect pending WELSH and STREET
3. Modify position: Then safely call provide/remove/burn liquidity functions
4. New tracking begins: Rewards now accumulate based on your updated LP balance

How Locked Liquidity is Tracked

The contract maintains two types of liquidity pools using these data variables:

;; Total reserves = locked + available
(define-data-var reserve-a uint u0)    ;; Total WELSH in contract
(define-data-var reserve-b uint u0)    ;; Total STREET in contract
 
;; Locked amounts (unavailable for withdrawal)
(define-data-var locked-a uint u0)     ;; Locked WELSH
(define-data-var locked-b uint u0)     ;; Locked STREET
(define-data-var locked-lp uint u0)    ;; LP tokens representing locked liquidity

Available liquidity is calculated dynamically:

(aval-a (if (>= res-a lock-a) (- res-a lock-a) u0))
(aval-b (if (>= res-b lock-b) (- res-b lock-b) u0))

Practical Example: How the System Works

Let’s trace through a complete scenario:

Initial State: Empty exchange

• reserve-a: 0 WELSH, locked-a: 0 WELSH, Available: 0 WELSH

Step 1: Contract owner calls provide-initial-liquidity(1000 WELSH, 119000 STREET)

• reserve-a: 1000 WELSH, locked-a: 0 WELSH, Available: 1000 WELSH
• Owner receives LP tokens based on geometric mean, establishes 1:119 ratio
• Creates fair foundation for community LP participation

Step 2: Contract owner calls lock-liquidity(500 WELSH)

• reserve-a: 1500 WELSH, locked-a: 500 WELSH, Available: 1000 WELSH
• locked-lp increases by calculated amount (tracking only, no real tokens minted)
• Creates permanent base liquidity that cannot be withdrawn

Step 3: User calls provide-liquidity(500 WELSH)

• reserve-a: 2000 WELSH, locked-a: 500 WELSH, Available: 1500 WELSH
• User receives LP tokens representing their share of available liquidity
• Available liquidity becomes the tradeable portion

Step 4: User calls remove-liquidity and pays 50 WELSH tax

• User receives their share minus tax
• Tax (50 WELSH) gets added to locked-a
• locked-a becomes 550 WELSH
• Locked liquidity grows over time through withdrawal taxes

Step 5: Someone calls burn-liquidity with their LP tokens

• LP token supply decreases
• All remaining LP holders now own a larger percentage of available reserves
• No effect on locked amounts - this is purely LP token economics

Critical Distinctions

lock vs burn

provide vs provide-initial

Reserve vs Available Liquidity

• Total reserves = locked + available liquidity
• Available liquidity = what’s actually tradeable and withdrawable by users
• Locked liquidity = permanently committed base liquidity that grows through taxes
• LP tokens represent both pools, but locked-lp specifically tracks the locked portion

Why This System Matters

1. Locked liquidity grows over time through taxes collected on withdrawals
2. Available liquidity provides normal AMM functionality for users
3. Burned LP tokens create value for remaining holders without affecting the locked base
4. Protocol-owned liquidity ensures the exchange always has trading depth
5. Tax collection continuously strengthens the permanent liquidity foundation
6. Fair initial distribution prevents first-mover advantage in LP token allocation
7. Flexible deployment adapts to market conditions at launch

Strategic Deployment Flow: From Idle WELSH to Active Economy

1. Initial Setup: Contract owner calls provide-initial-liquidity based on current WELSH market price, establishing fair pool ratio
2. Economic Activation: Contract owner calls lock-liquidity to create permanent base liquidity foundation
3. Community Commitment: Contract owner gradually calls burn-liquidity to sacrifice their outsized LP share, proving dedication to community benefit
4. Flywheel Engagement: WELSH holders call provide-liquidity to transform their idle assets into yield-generating CREDIT tokens with STREET emission rewards
5. Sustainable Growth: Withdrawal taxes continuously expand the locked base while LP burning increases reward share for community