Zenith SDK

A comprehensive JavaScript/TypeScript SDK for Zenith Protocols, providing easy-to-use interfaces for both Vault and Trading protocols on Stellar/Soroban.

Features

• Vault Protocol Support: Complete vault functionality including deposits, withdrawals, redemptions, and strategy management
• Trading Protocol Support: Full trading capabilities with position management, risk controls, and market operations
• TypeScript Support: Full TypeScript definitions for better developer experience
• Multiple Module Formats: Supports both CommonJS and ES Modules
• Network Support: Built-in support for Stellar testnet and mainnet

Installation

npm install @zenith-protocols/zenith-sdk

Quick Start

Import the SDK

// Import everything
import {
  VaultContract,
  TradingContract,
  Networks,
} from "@zenith-protocols/zenith-sdk";

// Or import specific modules
import { VaultContract } from "@zenith-protocols/zenith-sdk/vault";
import { TradingContract } from "@zenith-protocols/zenith-sdk/trading";
import { Networks } from "@zenith-protocols/zenith-sdk/core";

Vault Operations

import {
  VaultContract,
  VaultState,
  Networks,
} from "@zenith-protocols/zenith-sdk";

// Create a vault contract instance
const vaultContract = new VaultContract("vault_contract_address");

// Load vault state
const vaultState = await VaultState.load(
  Networks.testnet,
  "vault_contract_address"
);

// Deposit tokens
const depositOp = vaultContract.deposit({
  tokens: BigInt(1000000000), // 1000 tokens (with 7 decimals)
  receiver: "user_address",
  owner: "user_address",
});

// Request redemption
const redeemOp = vaultContract.requestRedeem({
  shares: BigInt(500000000), // 500 shares
  owner: "user_address",
});

Trading Operations

import { TradingContract, Networks } from "@zenith-protocols/zenith-sdk";

// Create a trading contract instance
const tradingContract = new TradingContract("trading_contract_address");

// Initialize the contract (owner only)
const initializeOp = tradingContract.initialize({
  name: "Trading Contract",
  vault: "vault_contract_address",
  config: {
    oracle: "oracle_address",
    caller_take_rate: BigInt(100000), // 1% in SCALAR_7
    max_positions: 10,
  },
});

// Create a position
const createPositionOp = tradingContract.createPosition({
  user: "user_address",
  asset: { tag: "Stellar", values: ["asset_address"] },
  collateral: BigInt(1000000000), // 1000 collateral
  notional_size: BigInt(5000000000), // 5000 notional size
  is_long: true,
  entry_price: BigInt(50000000), // 50.00 price
});

// Submit trading actions
const submitOp = tradingContract.submit({
  caller: "caller_address",
  requests: [
    {
      action: RequestType.Close,
      position: 1,
    },
    {
      action: RequestType.SetStopLoss,
      position: 2,
      data: BigInt(45000000), // 45.00 stop loss
    },
  ],
});

API Reference

Core Module

Networks

Pre-configured network constants for easy access to Stellar networks.

import { Networks } from "@zenith-protocols/zenith-sdk/core";

// Testnet configuration
const testnet = Networks.testnet;

// Mainnet configuration
const mainnet = Networks.mainnet;

Utils

Common utility functions for working with Stellar/Soroban contracts.

import {
  descale,
  scale,
  getTokenBalance,
} from "@zenith-protocols/zenith-sdk/core";

// Convert contract values to JavaScript numbers
const value = descale(BigInt(1000000000), 7); // 1000.0

// Convert JavaScript numbers to contract values
const contractValue = scale(1000.0, 7); // BigInt(1000000000)

// Get token balance
const balance = await getTokenBalance(
  Networks.testnet,
  "token_address",
  "user_address"
);

Vault Module

VaultContract

Main contract class for vault operations.

import { VaultContract } from "@zenith-protocols/zenith-sdk/vault";

const vault = new VaultContract("contract_address");

// Read operations
const token = vault.token();
const shareToken = vault.shareToken();
const totalShares = vault.totalShares();

// Write operations
const depositOp = vault.deposit({ tokens, receiver, owner });
const mintOp = vault.mint({ shares, receiver, owner });
const redeemOp = vault.redeem({ receiver, owner });

Vault

Class for loading and managing vault state.

import { Vault } from "@zenith-protocols/zenith-sdk/vault";

const state = await Vault.load(Networks.testnet, "vault_address");

// Access vault properties
console.log(state.token); // Underlying token address
console.log(state.sharePrice()); // Current share price
console.log(state.totalBorrowed()); // Total borrowed by strategies

Redemption

Class for managing redemption requests.

import { Redemption } from "@zenith-protocols/zenith-sdk/vault";

const redeem = await Redemption.load(
  Networks.testnet,
  "vault_address",
  "user_address"
);

if (redeem) {
  console.log(redeem.isReady()); // Check if redemption is ready
  console.log(redeem.getTimeRemaining()); // Time remaining in seconds
}

Trading Module

TradingContract

Main contract class for trading operations.

import { TradingContract } from "@zenith-protocols/zenith-sdk/trading";

const trading = new TradingContract("contract_address");

// Admin operations
const initializeOp = trading.initialize({ name, vault, config });
const setConfigOp = trading.setConfig(config);
const queueSetMarketOp = trading.queueSetMarket({ asset, config });
const cancelSetMarketOp = trading.cancelSetMarket(asset);
const setMarketOp = trading.setMarket(asset);
const setStatusOp = trading.setStatus(status);

// Trading operations
const createPositionOp = trading.createPosition({
  user,
  asset,
  collateral,
  notional_size,
  is_long,
  entry_price,
});
const submitOp = trading.submit({ caller, requests });

// Ownership operations
const getOwnerOp = trading.getOwner();
const transferOwnershipOp = trading.transferOwnership(
  new_owner,
  live_until_ledger
);
const acceptOwnershipOp = trading.acceptOwnership();
const renounceOwnershipOp = trading.renounceOwnership();

// Upgrade
const upgradeOp = trading.upgrade(wasm_hash);

Trading

Load and manage overall trading contract state.

import { Trading } from "@zenith-protocols/zenith-sdk/trading";

// Load trading contract state
const tradingState = await Trading.load(network, tradingContractId, [
  "USDC",
  "BTC",
]);

// Get statistics
const stats = tradingState.getStats();
console.log(`Total markets: ${stats.totalMarkets}`);
console.log(`Total collateral: ${stats.totalCollateral}`);

// Get user positions
const userPositions = await Trading.loadUserPositions(
  network,
  tradingContractId,
  userId
);

Market

Load and manage individual market state.

import { Market } from "@zenith-protocols/zenith-sdk/trading";

// Load market state
const market = await Market.load(network, tradingContractId, asset);

// Check market status
if (market.isEnabled()) {
  console.log(`Market utilization: ${market.utilization()}`);
  console.log(`Long/Short ratio: ${market.longShortRatio()}`);
}

// Check queued initialization
if (market.isQueuedInitReady()) {
  console.log("Market ready for activation");
}

PositionClass

Load and manage individual position state.

import { PositionClass } from "@zenith-protocols/zenith-sdk/trading";

// Load position
const position = await PositionClass.load(
  network,
  tradingContractId,
  positionId
);

if (position && position.isOpen()) {
  // Calculate PnL
  const pnl = position.pnl(currentPrice);
  console.log(`PnL: ${pnl}`);

  // Check stop loss
  if (position.isStopLossTriggered(currentPrice)) {
    console.log("Stop loss triggered");
  }
}

// Load user positions
const userPositions = await PositionClass.loadUserPositions(
  network,
  tradingContractId,
  userId
);

Types

The SDK provides comprehensive TypeScript types for all operations:

import type {
  VaultConstructorArgs,
  DepositArgs,
  TradingConfig,
  MarketConfig,
  Position,
  Asset,
  Request,
  RequestType,
  SubmitResult,
  TradingEventType,
  TradingEvent,
} from "@zenith-protocols/zenith-sdk";

Building from Source

# Clone the repository
git clone https://github.com/zenith-protocols/zenith-sdk.git
cd zenith-sdk

# Install dependencies
npm install

# Build the SDK
npm run build

# Run tests
npm test

# Type checking
npm run typecheck

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For support and questions, please open an issue on GitHub or contact the Zenith team.