SDK Overview

The @bitsage/sdk package is the TypeScript client for the Obelysk Protocol. It wraps all on-chain interactions — privacy pools, dark pool auctions, stealth payments, staking, and more — into a single ObelyskClient with 10 typed sub-clients.

Sub-Clients

Tests

v1.0.1

Version

Live

Mainnet

Installation

npm install @bitsage/sdk

Import Paths

Path	Contents
`@bitsage/sdk/obelysk`	Core client, all sub-clients, contract addresses, crypto utilities
`@bitsage/sdk/privacy`	ElGamal key generation, encryption/decryption, Schnorr proofs
`@bitsage/sdk/react`	React hooks for wallet connection and protocol state

Configuration

import { ObelyskClient } from '@bitsage/sdk/obelysk';

const obelysk = new ObelyskClient({
  network: 'mainnet',               // 'mainnet' or 'sepolia'
  rpcUrl: 'https://your-rpc.com',   // Starknet JSON-RPC endpoint
  account,                           // starknet.js Account (optional, for write ops)
  privacyPrivateKey: '0xabc...',     // ElGamal private key (optional, auto-generated)
  relayerUrl: 'https://vm31.bitsage.network', // VM31 relayer (optional)
});

Read-Only Mode

The account field is only required for transactions (deposits, swaps, staking). Read-only queries — checking pool stats, epoch info, orderbook depth — work without it.

Sub-Clients

The ObelyskClient exposes 10 sub-clients, each handling a specific protocol feature:

🏊

privacyPool

Deposit/withdraw shielded tokens with Merkle proofs and range proofs

🌑

darkPool

Commit-reveal batch auction trading with encrypted balances

👻

stealth

Send tokens to ephemeral one-time stealth addresses

🔐

confidentialTransfer

ElGamal encrypted peer-to-peer transfers with Schnorr proofs

⛏️

staking

Stake SAGE tokens, manage GPU prover tiers (15% APY)

🔀

router

Private balance management with auditor keys and nullifier tracking

🔄

swap

Privacy-preserving AMM swaps via Ekubo ILocker integration

🪙

vm31

UTXO privacy vault with Poseidon2-M31 hashing and denomination splitting

🌉

bridge

Bridge between VM31 UTXOs and Track 1 encrypted balances

📊

otc

Limit/market orders on the OTC orderbook with depth and trade history

Reading On-Chain State

import { ObelyskClient } from '@bitsage/sdk/obelysk';

const obelysk = new ObelyskClient({
  network: 'mainnet',
  rpcUrl: 'https://your-rpc.com',
});

// Dark Pool auction state
const epoch = await obelysk.darkPool.getEpochInfo();
console.log(`Epoch ${epoch.epochNumber} - Phase: ${epoch.phase}`);

// Privacy Pool statistics
const stats = await obelysk.privacyPool.getPoolStats('eth');
console.log('ETH pool deposits:', stats.totalDeposits);

// Staking info
const staked = await obelysk.staking.getTotalStaked();
console.log('Total SAGE staked:', staked);

// OTC orderbook depth
const depth = await obelysk.otc.getOrderbookDepth('SAGE/STRK');
console.log('Best bid:', depth.bids[0]?.price);
console.log('Best ask:', depth.asks[0]?.price);

Utility Functions

import {
  parseAmount,
  formatAmount,
  getContracts,
  MAINNET_TOKENS,
  TOKEN_DECIMALS,
} from '@bitsage/sdk/obelysk';

// Parse "1.5" ETH to bigint (1500000000000000000n)
const wei = parseAmount('1.5', 'eth');

// Format back to human-readable
const display = formatAmount(wei, 'eth'); // "1.5"

// Get all contract addresses for a network
const contracts = getContracts('mainnet');

Next Steps

Privacy Features — deposits, transfers, stealth payments, dark pool
Trading and Staking — OTC orders, shielded swaps, prover staking
VM31 UTXO Vault — UTXO-based privacy with denomination splitting
MCP Integration — let AI assistants interact with Obelysk