Stellar DeFi SDK

A comprehensive, easy-to-use TypeScript SDK for interacting with Decentralized Finance (DeFi) protocols on the Stellar network using Soroban smart contracts.

🚀 Features

• 🏦 Vaults: Simple interface for token deposits and interest-bearing vaults.
• 💱 Swap Pools: Automated Market Maker (AMM) interactions for liquidity and asset swaps.
• ⚖️ Governance: Propose, vote on, and execute protocol changes.
• 🛠️ Built-in Utilities: Helpers for ScVal conversions and address management.

📦 Installation

Install the SDK via npm:

npm install @samuel_birhanu/stellar-defi-sdk

Ensure you have @stellar/stellar-sdk installed as well:

npm install @stellar/stellar-sdk

⚙️ Quick Start

Initialize the DefiClient to connect to either Stellar Testnet or Mainnet.

import { DefiClient } from '@samuel_birhanu/stellar-defi-sdk';

// Initialize for Testnet
const client = new DefiClient('testnet');

// Access the underlying RPC server
console.log(client.rpc.server);

🏗️ Core Modules

1. Vault Client

Manage deposits and withdrawals for any Soroban-based vault.

import { VaultClient, DefiClient } from '@samuel_birhanu/stellar-defi-sdk';

const client = new DefiClient('testnet');
const vault = new VaultClient(client, 'CONTRACT_ID_HERE');

// Deposit tokens
const depositTx = vault.deposit('USER_ADDRESS', 1000n);

// Withdraw tokens
const withdrawTx = vault.withdraw('USER_ADDRESS', 500n);

// Check balance
const balanceQuery = vault.balance('USER_ADDRESS');

2. Swap Pool Client

Interact with liquidity pools to trade assets and manage liquidity.

import { SwapPoolClient, DefiClient } from '@samuel_birhanu/stellar-defi-sdk';

const client = new DefiClient('testnet');
const pool = new SwapPoolClient(client, 'POOL_CONTRACT_ID');

// Add Liquidity
const addLiq = pool.addLiquidity('USER_ADDRESS', 1000n, 1000n);

// Swap Asset A for Asset B
const swap = pool.swapAforB('USER_ADDRESS', 100n);

// Calculate output amount manually using math utilities
import { getAmountOut } from '@samuel_birhanu/stellar-defi-sdk/contracts/swapPool/math';
const expectedOut = getAmountOut(100n, 10000n, 10000n);

3. Governance Client

Participate in decentralized governance protocols.

import { GovernanceClient, DefiClient } from '@samuel_birhanu/stellar-defi-sdk';

const client = new DefiClient('testnet');
const gov = new GovernanceClient(client, 'GOV_CONTRACT_ID');

// Create a proposal
const proposal = gov.propose('USER_ADDRESS', 'Increase network fees', 5000);

// Vote on a proposal (true = Support, false = Against)
const vote = gov.vote('USER_ADDRESS', 1, true);

// Execute an approved proposal
const execution = gov.execute(1);

🛠️ Utilities

The SDK provides powerful utilities to handle Stellar's native data formats.

import { toI128, toU32, toAddress } from '@samuel_birhanu/stellar-defi-sdk/utils';

const scValLargeInt = toI128(1000000n);
const scValUint32 = toU32(42);
const scValAddress = toAddress('GD...');

📁 Project Structure

| File | Description | |------|-------------| | src/client/defiClient.ts | Main entry point for the SDK. | | src/client/rpc.ts | Handles connectivity to Stellar RPC nodes. | | src/contracts/vault/ | Vault interaction logic and types. | | src/contracts/swapPool/ | AMM/Swap pool logic and math utilities. | | src/contracts/governance/ | DAO governance tools. | | src/utils/ | Low-level converters for ScVal and Addresses. | | src/config/networks.ts | Network-specific configurations (Testnet/Mainnet). |

📜 Development

To build the SDK from source:

npm run build

This will generate CommonJS and ESM bundles in the dist directory.

🛡️ License

ISC