@vols/v2-sdk

A TypeScript SDK for building applications on top of VOLS Protocol V2, a decentralized exchange protocol built on the Hedera blockchain.

Description

The VOLS V2 SDK provides developers with a set of tools to interact with the VOLS V2 protocol on Hedera. It includes functionality for creating and managing liquidity pairs, calculating swap routes, executing trades, and handling various token operations within the Hedera ecosystem.

Installation

Install the SDK using npm, yarn, or pnpm:

npm install @vols/v2-sdk
# or
yarn add @vols/v2-sdk
# or
pnpm add @vols/v2-sdk

Dependencies

This SDK depends on the following packages:

• @ethersproject/address: ^5.7.0
• @ethersproject/bignumber: ^5.7.0
• @ethersproject/solidity: ^5.7.0
• @vols/sdk-core: ^1.1.0
• jsbi: 3.1.4
• tiny-invariant: ^1.1.0
• tiny-warning: ^1.0.3

Core Features

Pairs

The Pair class represents a trading pair in the VOLS V2 protocol on Hedera. It provides methods for:

• Computing pair addresses
• Getting token prices
• Calculating optimal swap amounts
• Managing liquidity

Routes

The Route class helps determine the best path for token swaps through one or more pairs, optimizing for price efficiency on the Hedera network.

Trades

The Trade class provides functionality for executing trades between tokens, including:

• Price impact calculations
• Slippage protection
• Execution price estimation
• Best trade path finding

Usage Examples

Creating a Pair

import { Token } from '@vols/sdk-core'
import { Pair } from '@vols/v2-sdk'

// Define tokens on Hedera
const HBAR = new Token(
  295, // Hedera mainnet chain ID
  '0x0000000000000000000000000000000000000000', // HBAR representation
  18,
  'HBAR',
  'Hedera'
)

const USDC = new Token(
  295,
  '0x...',  // USDC token address on Hedera
  6,
  'USDC',
  'USD Coin'
)

// Create a pair
const pair = new Pair(
  CurrencyAmount.fromRawAmount(HBAR, '100000000000000000000'),
  CurrencyAmount.fromRawAmount(USDC, '200000000')
)

Executing a Trade

import { TradeType, Percent } from '@vols/sdk-core'
import { Trade, Route } from '@vols/v2-sdk'

// Create a route
const route = new Route([pair], HBAR, USDC)

// Create a trade
const trade = new Trade(
  route,
  CurrencyAmount.fromRawAmount(HBAR, '1000000000000000000'),
  TradeType.EXACT_INPUT
)

// Configure trade options
const options = {
  allowedSlippage: new Percent('50', '10000'), // 0.5%
  ttl: 1200, // 20 minutes
  recipient: 'your-hedera-account-id'
}

// Get swap parameters
const swapParameters = Router.swapCallParameters(trade, options)

Error Handling

The SDK includes specialized error classes to handle common issues:

• InsufficientReservesError: Thrown when a pair has insufficient reserves for a desired output amount
• InsufficientInputAmountError: Thrown when the input amount is too small to produce any output

Hedera-Specific Considerations

This SDK is specifically designed to work with the Hedera blockchain and the VOLS protocol. It handles Hedera's unique addressing system and token standards while providing a familiar interface for developers coming from other EVM-compatible chains.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• GitHub Repository
• VOLS Protocol Documentation
• Hedera Developer Portal