BTC SOL UserPosition Decoder

A Solana program client for decoding and analyzing UserPosition accounts and tracking rewards in the BTC SOL synthetic market. This tool interacts with the Synthetic Market program to fetch user positions across multiple strategy groups (mSOL, JupSOL, kySOL) and calculate underlying token amounts and ZBTC rewards.

Installation

pnpm install

Build

pnpm build

Configuration

Setup your .env file based on .env.example:

SOLANA_RPC_URL=<your_solana_rpc_url>

Usage

1. Fetch UserPosition Data

Fetches and decodes UserPosition PDAs for a specific user address across all strategy groups.

pnpm start userposition <user_address>

Example:

pnpm build && pnpm start userposition 5ic8MKAFCDVj5mRozt23uFAKKoWGqwULQER3B9mAsLfx

Expected Output:

Fetching and decoding UserPosition accounts...
Connected to: <your_solana_rpc_url>...
Fetching UserPositions for: 5ic8MKAFCDVj5mRozt23uFAKKoWGqwULQER3B9mAsLfx

Checking strategy group: CMBwsHiUnih1VAzENzoNKTq8tyRaCpD2zBgBUm47sN6h
✅ UserPosition found for strategy: CMBwsHiUnih1VAzENzoNKTq8tyRaCpD2zBgBUm47sN6h
   Market: CyRC3kBmmhpew1J4Doahy9Lv9Wwkd9rNd82MQGD5Ri2K
   Owner: 5ic8MKAFCDVj5mRozt23uFAKKoWGqwULQER3B9mAsLfx
   Synthetic Amount: 786939501 (0.786939501 btcSOL)
   Underlying Amount: 0.596999999 mSOL
   Exchange Ratio: 1.318156619273

Checking strategy group: 9HGpvmW1Lv2pqKkbM41pGm7ApMjgdXt7Refdv5hoFejJ
✅ UserPosition found for strategy: 9HGpvmW1Lv2pqKkbM41pGm7ApMjgdXt7Refdv5hoFejJ
   Synthetic Amount: 678857337 (0.678857337 btcSOL)
   Underlying Amount: 0.596999999 jupSOL
   Exchange Ratio: 1.137114468527

Checking strategy group: 67zGEwrzVJvn9owJR8aL693K1eMoH28WiDKDE17xNmf8
✅ UserPosition found for strategy: 67zGEwrzVJvn9owJR8aL693K1eMoH28WiDKDE17xNmf8
   Synthetic Amount: 735989801 (0.735989801 btcSOL)
   Underlying Amount: 0.597000000 kySOL
   Exchange Ratio: 1.232813737832

2. Fetch Reward Data

Fetches unclaimed and historical ZBTC rewards for a user across all strategy groups.

pnpm start reward <user_address>

Example:

pnpm build && pnpm start reward 5ic8MKAFCDVj5mRozt23uFAKKoWGqwULQER3B9mAsLfx

Expected Output:

Fetching and decoding Reward accounts...
================================================================================
Connected to: <your_solana_rpc_url>...

Processing strategy group: CMBwsHiUnih1VAzENzoNKTq8tyRaCpD2zBgBUm47sN6h
--------------------------------------------------------------------------------
Fetching historical rewards from API...

📊 Strategy Group Summary:
  Unclaimed Rewards:    0.00000538 ZBTC
  Historical Claimed:   0.00000100 ZBTC
  Total Rewards:        0.00000638 ZBTC

Processing strategy group: 9HGpvmW1Lv2pqKkbM41pGm7ApMjgdXt7Refdv5hoFejJ
--------------------------------------------------------------------------------
📊 Strategy Group Summary:
  Unclaimed Rewards:    0.00000476 ZBTC
  Historical Claimed:   0.00000050 ZBTC
  Total Rewards:        0.00000526 ZBTC

Processing strategy group: 67zGEwrzVJvn9owJR8aL693K1eMoH28WiDKDE17xNmf8
--------------------------------------------------------------------------------
📊 Strategy Group Summary:
  Unclaimed Rewards:    0.00000600 ZBTC
  Historical Claimed:   0.00000150 ZBTC
  Total Rewards:        0.00000750 ZBTC

================================================================================
📈 TOTAL ACROSS ALL STRATEGY GROUPS:
================================================================================
  Total Unclaimed Rewards:    0.00001614 ZBTC
  Total Historical Claimed:   0.00000300 ZBTC
  Grand Total Rewards:        0.00001914 ZBTC
================================================================================

Features

• Multi-Strategy Support: Tracks positions across mSOL, JupSOL, and kySOL strategy groups
• UserPosition Decoding: Fetches and decodes on-chain UserPosition PDAs
• Price Calculations: Calculates underlying token amounts using exchange ratios from strategy group epoch data
• Unclaimed Rewards: Simulates claimTreasuryToken transactions and parses events to extract claimable ZBTC amounts
• Historical Rewards: Fetches previously claimed rewards from BTC SOL API
• Comprehensive Tracking: Displays total rewards (unclaimed + historical) with proper decimal formatting

Architecture

Core Components

• src/index.ts: CLI entry point that routes commands
• src/userposition.ts: UserPosition fetching and underlying token calculations
• src/reward.ts: Reward tracking (unclaimed + historical)
• src/constants.ts: Program IDs, seeds, and strategy group addresses
• src/idl.ts: TypeScript IDL types for the Synthetic Market program
• src/util.ts: Utility functions for program setup and PDA derivation

Strategy Groups

The tool supports three liquid staking token strategy groups:

1. mSOL Strategy (CMBwsHiUnih1VAzENzoNKTq8tyRaCpD2zBgBUm47sN6h)
2. jupSOL Strategy (9HGpvmW1Lv2pqKkbM41pGm7ApMjgdXt7Refdv5hoFejJ)
3. kySOL Strategy (67zGEwrzVJvn9owJR8aL693K1eMoH28WiDKDE17xNmf8)

Technical Details

Price Calculation

Underlying token amounts are calculated by dividing synthetic amounts by exchange ratios from strategy group epoch data:

underlying_amount = synthetic_amount / (exchange_ratio / 1e12)

The exchange ratio is scaled by 1e12 for precision.

Reward Calculation

Rewards are calculated in two parts:

1. Unclaimed Rewards: Simulates a claimTreasuryToken transaction and parses the treasuryTokenClaimed event to extract the claimable amount
2. Historical Rewards: Queries the BTC SOL API endpoint to get previously claimed amounts
3. Total Rewards: Sum of unclaimed and historical rewards, displayed in ZBTC (8 decimals)

License

MIT