TypeScript SDK: Getting Started

This guide covers everything you need to start integrating with Vanna Protocol from a TypeScript/JavaScript environment — reading pool state, checking health factors, and executing margin operations.

Prerequisites

Node.js 20+ (required by the Stellar SDK)
A Stellar testnet account (create at Stellar Laboratory)
Freighter browser extension for wallet signing (browser only)
Testnet XLM from the Stellar Testnet Faucet

Installation

npm install @stellar/stellar-sdk @stellar/freighter-api

Package	Version	Purpose
`@stellar/stellar-sdk`	^14.x	Soroban contract calls, transaction building, XDR encoding
`@stellar/freighter-api`	^6.x	Browser wallet connection and signing

Network Configuration

import { SorobanRpc, Networks } from '@stellar/stellar-sdk';

const NETWORK_PASSPHRASE = Networks.TESTNET;
// 'Test SDF Network ; September 2015'

const server = new SorobanRpc.Server(
  'https://soroban-testnet.stellar.org',
  { allowHttp: false }
);

Contract Addresses

All addresses are available in Deployed Contracts. Import them centrally:

export const CONTRACTS = {
  REGISTRY:        'CC35XWCH7SCQROTNW7PA6HZKP4JMNSVV2K7CX3HY2PSI2MI2ZQQH73ID',
  ORACLE:          'CB72D6SOUHUTCESXYOQOBMP6MRSH47NBYIBH73BBRH3ZRT53LPTB6R7V',
  RATE_MODEL:      'CCJAUPCU6EIFQK6GTAAYLW3Y4YETJAAUPAGBPFGQ2OUJPSW3WWHUCL2Z',
  RISK_ENGINE:     'CBL7RCG5H4VIZCNF7BRM2FQFXK7N5KRQKW7ZVEQZJKNXHA6FEU4OXK5I',
  ACCOUNT_MANAGER: 'CAK2IJIO2SKZWUODY4G7ZRIUUIIMJUUAIXE3I5YTQ5QYNSS2RYJ3P4CV',
  TRACKING_TOKEN:  'CA24GDWO63ZXNMW5FLWF2KMZ5DCF3DO7J3RYABFICDIDHH4A342RD2TR',

  // Lending pools
  POOL_XLM:        'CBA4E4ZMXUKCDTNT7LDKSO3LGNGKHRCE4GUVPSRCAKU3TKAONUY7SVOB',
  POOL_USDC:       'CABLEI2ZPCWLO2FQRHJJYR7JW75BCCPN2ZIV5BX7CHPXZT4CZVTGUOBU',

  // vTokens
  VXLM:            'CCQAAPNBYF6I7PRM2NZ4NRDYZUVJJANMX3RZ4ZLMQH6Z5WAUL2MHU2RZ',
  VUSDC:           'CDAJHQEJ26EBBGV2UYSR5S5LLA6F3A7KQISLPY5JMOL77RUDBEWG3T6Y',

  // Native tokens
  XLM_SAC:         'CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC',
  USDC:            'CAQCFVLOBK5GIULPNZRGATJJMIZL5BSP7X5YJVMGCPTUEPFM4AVSRCJU',
} as const;

Simulating (Reading) Contracts

For read-only operations, use server.simulateTransaction(). No signing required.

import {
  Contract,
  TransactionBuilder,
  Account,
  SorobanRpc,
  scValToNative,
  nativeToScVal,
  xdr,
} from '@stellar/stellar-sdk';

const NETWORK_PASSPHRASE = 'Test SDF Network ; September 2015';

async function simulateContractCall(
  contractAddress: string,
  method: string,
  args: xdr.ScVal[] = [],
): Promise<xdr.ScVal> {
  const contract = new Contract(contractAddress);
  const account = new Account('GAAZI4TCR3TY5OJHCTJC2A4QSY6CJWJH5IAJTGKIN2ER7LBNVKOCCWN', '0');

  const tx = new TransactionBuilder(account, {
    fee: '100',
    networkPassphrase: NETWORK_PASSPHRASE,
  })
    .addOperation(contract.call(method, ...args))
    .setTimeout(30)
    .build();

  const result = await server.simulateTransaction(tx);

  if (SorobanRpc.Api.isSimulationError(result)) {
    throw new Error(`Simulation failed: ${result.error}`);
  }

  return result.result!.retval;
}

Reading Pool State

// Get total borrows from the XLM pool
const borrowsScVal = await simulateContractCall(CONTRACTS.POOL_XLM, 'get_borrows');
const borrowsWad = scValToNative(borrowsScVal) as bigint;
// borrowsWad is in 10^18 scale. Divide by 10^7 for XLM (7 decimals), then by 10^11.

// Get total liquidity
const liquidityScVal = await simulateContractCall(CONTRACTS.POOL_XLM, 'get_total_liquidity_in_pool');
const liquidityWad = scValToNative(liquidityScVal) as bigint;

// Compute utilization
const WAD = 10n ** 18n;
const utilization = (borrowsWad * WAD) / (liquidityWad + borrowsWad);
// utilization is in WAD (10^18 = 100%)

Reading a User’s Margin Account

// Step 1: Find the user's SmartAccount via Registry
const accountsScVal = await simulateContractCall(
  CONTRACTS.REGISTRY,
  'get_accounts',
  [nativeToScVal(userWalletAddress, { type: 'address' })]
);
const accounts = scValToNative(accountsScVal) as string[];
const smartAccount = accounts[0]; // user's active margin account

// Step 2: Read health factor inputs
const collateralScVal = await simulateContractCall(
  CONTRACTS.RISK_ENGINE,
  'get_current_total_balance',
  [nativeToScVal(smartAccount, { type: 'address' })]
);
const collateralUsdWad = scValToNative(collateralScVal) as bigint;

const debtScVal = await simulateContractCall(
  CONTRACTS.RISK_ENGINE,
  'get_current_total_borrows',
  [nativeToScVal(smartAccount, { type: 'address' })]
);
const debtUsdWad = scValToNative(debtScVal) as bigint;

// Step 3: Compute health factor
const healthFactor = debtUsdWad > 0n
  ? (collateralUsdWad * WAD) / debtUsdWad
  : null; // no debt

Connecting a Freighter Wallet

import {
  requestAccess,
  getAddress,
  signTransaction,
} from '@stellar/freighter-api';

// Request wallet access (shows Freighter popup)
async function connectWallet(): Promise<string> {
  await requestAccess();
  const address = await getAddress();
  return address;
}

Executing Transactions

See Transaction Flow for the complete pattern: build → simulate → sign → submit.

Reading Oracle Prices

const priceScVal = await simulateContractCall(
  CONTRACTS.ORACLE,
  'get_price_latest',
  [nativeToScVal('XLM', { type: 'symbol' })]
);

const [price, decimals] = scValToNative(priceScVal) as [bigint, number];
// Convert to WAD: price_wad = price * (10^18 / 10^decimals)
const priceWad = price * (10n ** 18n) / (10n ** BigInt(decimals));

Handling Errors

Soroban errors from contract panics appear in simulation as SimulationError or in transaction results as invokeHostFunctionError. Parse them:

import { SorobanRpc } from '@stellar/stellar-sdk';

const result = await server.simulateTransaction(tx);

if (SorobanRpc.Api.isSimulationError(result)) {
  // Contract panicked or insufficient resources
  console.error('Simulation error:', result.error);
  throw new Error(result.error);
}

if (SorobanRpc.Api.isSimulationSuccess(result) && result.result?.auth) {
  // Check for auth errors — missing require_auth()
}

Common error patterns:

InsufficientBalance — caller doesn’t have enough tokens
InsufficientPoolBalance — pool can’t cover withdrawal
RiskEngineNotInitialized — missing registry setup
Health factor check failure — logged as a contract panic with specific error code

Next Steps

Transaction Flow

Build, simulate, sign, and submit Soroban transactions step by step.

Mercury Indexer

Query historical events and transaction history via the Mercury indexer.

Integrate Lending

End-to-end guide for deposit and vToken redemption.

Integrate Margin

Create accounts, deposit collateral, and borrow assets.

Introduction

Contract Reference

TypeScript SDK

Integration Guides

TypeScript SDK: Getting Started

Prerequisites

Installation

Network Configuration

Contract Addresses

Simulating (Reading) Contracts

Reading Pool State

Reading a User’s Margin Account

Connecting a Freighter Wallet

Executing Transactions

Reading Oracle Prices

Handling Errors

Next Steps

Transaction Flow

Mercury Indexer

Integrate Lending

Integrate Margin

​Prerequisites

​Installation

​Network Configuration

​Contract Addresses

​Simulating (Reading) Contracts

​Reading Pool State

​Reading a User’s Margin Account

​Connecting a Freighter Wallet

​Executing Transactions

​Reading Oracle Prices

​Handling Errors

​Next Steps

Transaction Flow

Mercury Indexer

Integrate Lending

Integrate Margin

Prerequisites

Installation

Network Configuration

Contract Addresses

Simulating (Reading) Contracts

Reading Pool State

Reading a User’s Margin Account

Connecting a Freighter Wallet

Executing Transactions

Reading Oracle Prices

Handling Errors

Next Steps