normal-rust-types 0.1.1

A common Rust types library for the entire Normal Finance Ecosystem
Documentation

Normal Finance Rust Types

Crates.io Documentation License: Apache 2.0

A comprehensive Rust types library for the Normal Finance ecosystem, providing shared data structures, events, storage types, and error definitions for Soroban smart contracts.

Overview

Normal Finance is a decentralized finance platform built on Stellar's Soroban smart contract platform. This crate provides the foundational types used across all Normal Finance smart contracts, including:

  • Index Fund Management: Types for creating and managing tokenized index funds
  • Automated Market Maker (AMM): Pool management, liquidity provision, and trading types
  • Insurance Fund: Risk management and insurance claim structures
  • Oracle Integration: Price feed and oracle registry types
  • Access Control: Permission and role management types

Features

  • Soroban SDK Integration: Built specifically for Soroban smart contracts using soroban-sdk v22.0.1
  • Comprehensive Error Handling: Standardized error types across all contract interactions
  • Event Definitions: Structured event types for contract logging and monitoring
  • Storage Types: Optimized data structures for Soroban contract storage
  • Type Safety: Strongly-typed interfaces preventing common smart contract vulnerabilities

Installation

Add this to your Cargo.toml:

[dependencies]
normal-rust-types = "0.1.0"

Usage

Basic Import

use normal_rust_types::*;

Specific Module Imports

// Import specific modules as needed
use normal_rust_types::{
    errors::{PoolError, TokenError},
    types::{Pool, SwapParams, IndexInfo},
    events::{SwapEvent, PoolCreatedEvent},
    storage::{PoolStorage, AccessControlStorage}
};

Working with Pool Types

use normal_rust_types::{Pool, PoolTier, PoolStatus, SwapParams};
use soroban_sdk::{Env, Address, Symbol};

// Create a new pool configuration
let pool = Pool {
    token_b: token_address,
    base_asset: Symbol::new(&env, "USDC"),
    quote_asset: Symbol::new(&env, "XLM"),
    tier: PoolTier::Tier1,
    status: PoolStatus::Active,
    // ... other fields
};

// Define swap parameters
let swap_params = SwapParams {
    token_in: usdc_address,
    token_out: xlm_address,
    amount_in: 1000_0000000, // 1000 USDC (7 decimals)
    amount_out_min: 2500_0000000, // Minimum 2500 XLM expected
    to: user_address,
    // ... other fields
};

Working with Index Types

use normal_rust_types::{IndexInfo, Component};

// Define index components
let components = vec![
    Component {
        asset: Symbol::new(&env, "BTC"),
        weight: 4000, // 40% allocation
    },
    Component {
        asset: Symbol::new(&env, "ETH"),
        weight: 3000, // 30% allocation
    },
    Component {
        asset: Symbol::new(&env, "XLM"),
        weight: 3000, // 30% allocation
    },
];

// Create index info
let index_info = IndexInfo {
    address: index_contract_address,
    token_address: index_token_address,
    total_shares: 0,
    base_nav: 1_0000000, // Starting NAV of 1.0
    is_public: true,
    components,
    // ... other fields
};

Error Handling

use normal_rust_types::{PoolError, TokenError, ValidationError};

// Handle specific error types
match contract_result {
    Err(PoolError::InsufficientLiquidity) => {
        // Handle insufficient liquidity
    },
    Err(TokenError::InsufficientBalance) => {
        // Handle insufficient balance
    },
    Err(ValidationError::InvalidAmount) => {
        // Handle invalid amount
    },
    Ok(result) => {
        // Process successful result
    }
}

Module Structure

Types (types/)

Core data structures used across Normal Finance contracts:

  • amm_config: AMM configuration and settings
  • config: General configuration types
  • enums: Common enumerations (PoolTier, PoolStatus, etc.)
  • fees: Fee calculation and structure types
  • index: Index fund related types (IndexInfo, Component, etc.)
  • insurance_fund: Insurance and risk management types
  • oracle: Price oracle and registry types
  • pool: Liquidity pool types and structures
  • rebalance: Portfolio rebalancing types
  • rewards: Incentive and reward distribution types
  • trading: Trading and swap related types

Errors (errors/)

Comprehensive error definitions for all contract operations:

  • access_control_error: Permission and role errors
  • buffer_error: Buffer management errors
  • index_error: Index fund operation errors
  • insurance_fund_error: Insurance claim and management errors
  • liquidity_calculator_error: Liquidity calculation errors
  • math_error: Mathematical operation errors
  • oracle_error: Price feed and oracle errors
  • pool_error: Pool operation and validation errors
  • pool_router_error: Pool routing errors
  • storage_error: Data storage and retrieval errors
  • swap_error: Trading and swap errors
  • token_error: Token operation errors
  • upgrade_error: Contract upgrade errors
  • validation_error: Input validation errors

Events (events/)

Structured event types for contract logging:

  • access_control: Permission change events
  • amm_config: AMM configuration events
  • amm_pool: Pool lifecycle events
  • config: Configuration update events
  • factory: Contract deployment events
  • fees: Fee collection and update events
  • index: Index fund events
  • swap: Trading and swap events
  • upgrade: Contract upgrade events

Storage (storage/)

Optimized storage structures for Soroban contracts:

  • access_control: Role and permission storage
  • amm_pool: Pool state storage
  • buffer: Buffer management storage
  • factory: Factory contract storage
  • index: Index fund storage
  • insurance_fund: Insurance fund storage
  • swap_utility: Swap utility storage
  • token: Token storage structures
  • token_share: Token share storage
  • upgrade: Upgrade management storage

Contributing

We welcome contributions to improve and extend the Normal Finance type system. Please ensure that:

  1. All new types include proper documentation
  2. Error types include descriptive messages
  3. Changes maintain backward compatibility when possible
  4. Tests are included for new functionality

License

This project is licensed under the Apache License 2.0 - see the LICENSE.md file for details.

Authors

Links