multiliquid-svm-sdk 0.1.2

Unsigned transaction builders, account codecs, and quoting for Multiliquid on Solana
Documentation
//! Exact integer-string amount conversion, without floating-point arithmetic.
//!
//! Native amounts are bounded by `u128`, unlike JavaScript's arbitrary-precision
//! bigint. Use [`to_human_readable_signed`] for the signed `i128` domain. Decimal
//! counts are `u8`; all representable counts are supported without a power-of-ten
//! intermediate limiting formatting to 38 decimals.

use crate::error::{Result, SdkError};

/// Format a native amount, removing trailing fractional zeroes but never
/// rounding or discarding nonzero digits.
pub fn to_human_readable(amount: u128, decimals: u8) -> String {
    let mut digits = amount.to_string();
    if amount == 0 || decimals == 0 {
        return digits;
    }
    let decimals = usize::from(decimals);
    if digits.len() > decimals {
        digits.insert(digits.len() - decimals, '.');
    } else {
        let mut fractional = String::with_capacity(decimals + 2);
        fractional.push_str("0.");
        for _ in digits.len()..decimals {
            fractional.push('0');
        }
        fractional.push_str(&digits);
        digits = fractional;
    }
    let trimmed_len = digits.trim_end_matches('0').trim_end_matches('.').len();
    digits.truncate(trimmed_len);
    digits
}

/// Signed counterpart of [`to_human_readable`], including `i128::MIN`.
/// Parsing remains unsigned, matching TypeScript's `toNativeAmount` syntax.
pub fn to_human_readable_signed(amount: i128, decimals: u8) -> String {
    let mut formatted = to_human_readable(amount.unsigned_abs(), decimals);
    if amount < 0 {
        formatted.insert(0, '-');
    }
    formatted
}

// ECMAScript String.trim includes BOM, but not Unicode NEXT LINE (U+0085).
fn is_js_whitespace(character: char) -> bool {
    matches!(
        character,
        '\u{0009}'..='\u{000d}'
            | '\u{0020}'
            | '\u{00a0}'
            | '\u{1680}'
            | '\u{2000}'..='\u{200a}'
            | '\u{2028}'
            | '\u{2029}'
            | '\u{202f}'
            | '\u{205f}'
            | '\u{3000}'
            | '\u{feff}'
    )
}

/// Parse an unsigned decimal amount exactly. Signs, exponents, empty integer or
/// fractional parts, and excess decimal places (even zeroes) are rejected.
/// Values beyond `u128::MAX` return [`SdkError::MathOverflow`].
pub fn to_native_amount(human: &str, decimals: u8) -> Result<u128> {
    let value = human.trim_matches(is_js_whitespace);
    let (whole, fractional) = match value.split_once('.') {
        Some((whole, fractional)) if !fractional.is_empty() => (whole, fractional),
        Some(_) => {
            return Err(SdkError::InvalidInput(format!(
                "Invalid decimal amount: {human}"
            )))
        }
        None => (value, ""),
    };
    if whole.is_empty()
        || !whole.bytes().all(|byte| byte.is_ascii_digit())
        || !fractional.bytes().all(|byte| byte.is_ascii_digit())
    {
        return Err(SdkError::InvalidInput(format!(
            "Invalid decimal amount: {human}"
        )));
    }
    let decimals = usize::from(decimals);
    if fractional.len() > decimals {
        return Err(SdkError::InvalidInput(format!(
            "Too many decimal places: got {}, max {decimals}",
            fractional.len()
        )));
    }

    let mut amount = 0_u128;
    for digit in whole.bytes().chain(fractional.bytes()) {
        amount = amount
            .checked_mul(10)
            .and_then(|value| value.checked_add(u128::from(digit - b'0')))
            .ok_or(SdkError::MathOverflow)?;
    }
    for _ in fractional.len()..decimals {
        amount = amount.checked_mul(10).ok_or(SdkError::MathOverflow)?;
    }
    Ok(amount)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn signed_formatting_preserves_sign_and_handles_minimum_integer() {
        assert_eq!(to_human_readable_signed(-1, 6), "-0.000001");
        assert_eq!(to_human_readable_signed(-100_000_000, 6), "-100");
        assert_eq!(to_human_readable_signed(-239_520_240, 6), "-239.52024");
        assert_eq!(
            to_human_readable_signed(i128::MIN, 0),
            "-170141183460469231731687303715884105728"
        );
        assert_eq!(to_human_readable_signed(0, 6), "0");
    }

    #[test]
    fn trailing_zeroes_are_removed_without_truncating_precision() {
        assert_eq!(to_human_readable(2_000_000_001, 9), "2.000000001");
        assert_eq!(to_human_readable(239_520_240, 6), "239.52024");
        assert_eq!(to_native_amount("  001.20  ", 3).unwrap(), 1_200);
        assert!(to_native_amount("1.0000", 3).is_err());
        assert!(to_native_amount("1.0", 0).is_err());
        assert!(to_native_amount("0.0000001", 6).is_err());
    }

    #[test]
    fn parsing_rejects_signed_and_non_decimal_syntax() {
        for value in [
            "", "   ", "-1", "+1", ".5", "1.", "1e3", "1_000", "NaN", "Infinity", "1.2.3", "١",
        ] {
            assert!(to_native_amount(value, 6).is_err(), "accepted {value:?}");
        }
        assert_eq!(to_native_amount("\u{feff}1\u{00a0}", 0).unwrap(), 1);
        assert!(to_native_amount("\u{0085}1", 0).is_err());
    }

    #[test]
    fn maximum_native_amount_round_trips_and_overflow_is_explicit() {
        let maximum = "340282366920938463463374607431768211455";
        assert_eq!(to_native_amount(maximum, 0).unwrap(), u128::MAX);
        assert_eq!(to_human_readable(u128::MAX, 0), maximum);
        assert!(matches!(
            to_native_amount("340282366920938463463374607431768211456", 0),
            Err(SdkError::MathOverflow)
        ));
        assert!(matches!(
            to_native_amount(maximum, 1),
            Err(SdkError::MathOverflow)
        ));
        let text = to_human_readable(u128::MAX, 38);
        assert_eq!(to_native_amount(&text, 38).unwrap(), u128::MAX);
    }

    #[test]
    fn large_decimal_counts_do_not_require_an_overflowing_scale() {
        let text = to_human_readable(1, 255);
        assert_eq!(text, format!("0.{}1", "0".repeat(254)));
        assert_eq!(to_native_amount(&text, 255).unwrap(), 1);
        assert_eq!(to_native_amount("0", 255).unwrap(), 0);
        assert!(matches!(
            to_native_amount("1", 39),
            Err(SdkError::MathOverflow)
        ));
    }
}