satrush_client/

sats.rs

/// BTC value of a sats-vault share amount, as computed by [`sats_to_btc`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct BtcSharesValue {
    /// Value at the current exchange rate, before the claim fee.
    pub gross: u64,
    /// Fee withheld on claim; the payout is `gross - fee`.
    pub fee: u64,
}

#[derive(Debug, thiserror::Error)]
pub enum BtcSharesValueError {
    #[error("shares exceed the vault's issued shares")]
    InsufficientShares,
    #[error("claim fee bps exceed the 10000 denominator")]
    InvalidClaimFeeBps,
}

/// BTC value of `shares` against a vault holding `vault_amount` BTC with
/// `vault_shares` shares issued (`SatsVault::btc_amount` /
/// `SatsVault::btc_shares`). `claim_fee_bps` is
/// `SatrushConfig::sats_vault_claim_fee_bps`; pass `0` when only the gross
/// value matters. Zero `shares` value to zero without error; `shares`
/// exceeding `vault_shares` is rejected.
pub fn sats_to_btc(
    shares: u64,
    vault_amount: u64,
    vault_shares: u64,
    claim_fee_bps: u32,
) -> Result<BtcSharesValue, BtcSharesValueError> {
    const BPS_DENOMINATOR: u128 = 10_000;

    if claim_fee_bps as u128 > BPS_DENOMINATOR {
        return Err(BtcSharesValueError::InvalidClaimFeeBps);
    }
    if shares == 0 {
        return Ok(BtcSharesValue { gross: 0, fee: 0 });
    }
    if shares > vault_shares {
        return Err(BtcSharesValueError::InsufficientShares);
    }

    // shares <= vault_shares and claim_fee_bps <= BPS_DENOMINATOR, so
    // gross <= vault_amount and fee <= gross: both narrowing conversions are
    // lossless.
    let gross = (shares as u128 * vault_amount as u128 / vault_shares as u128) as u64;
    let fee = (gross as u128 * claim_fee_bps as u128 / BPS_DENOMINATOR) as u64;
    Ok(BtcSharesValue { gross, fee })
}

#[derive(Debug, thiserror::Error)]
pub enum BtcToSatsError {
    #[error("share amount is not computable for the vault state")]
    MathOverflow,
}

/// Shares minted for depositing `btc_amount` BTC into a vault holding
/// `vault_amount` BTC with `vault_shares` shares issued
/// (`SatsVault::btc_amount` / `SatsVault::btc_shares`): 1:1 while no shares
/// exist, otherwise scaled by the vault's `shares / assets` ratio and
/// floored. Errors when the vault has shares but no BTC, or the result
/// exceeds `u64::MAX`.
pub fn btc_to_sats(btc_amount: u64, vault_amount: u64, vault_shares: u64) -> Result<u64, BtcToSatsError> {
    if vault_shares == 0 {
        return Ok(btc_amount);
    }
    if vault_amount == 0 {
        return Err(BtcToSatsError::MathOverflow);
    }
    u64::try_from(btc_amount as u128 * vault_shares as u128 / vault_amount as u128)
        .map_err(|_| BtcToSatsError::MathOverflow)
}

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

    /// 10% claim fee, matching the program's default
    /// `SatrushConfig::sats_vault_claim_fee_bps`.
    const CLAIM_FEE_BPS: u32 = 1_000;

    #[test]
    fn values_shares_at_the_current_exchange_rate() {
        // 100 BTC / 100 shares: 50 shares are worth 50 gross, 5 fee (10%).
        assert_eq!(sats_to_btc(50, 100, 100, CLAIM_FEE_BPS).unwrap(), BtcSharesValue { gross: 50, fee: 5 });
    }

    #[test]
    fn full_drain_of_appreciated_vault_matches_on_chain_payout() {
        // 55 BTC / 50 shares (rate 1.1): all 50 shares -> gross 55, fee 5,
        // matching the on-chain redeem payout of 50.
        assert_eq!(sats_to_btc(50, 55, 50, CLAIM_FEE_BPS).unwrap(), BtcSharesValue { gross: 55, fee: 5 });
    }

    #[test]
    fn floors_gross_and_fee() {
        // 10 BTC / 3 shares: 1 share -> gross floor(10/3) = 3, fee floor(300/10000) = 0.
        assert_eq!(sats_to_btc(1, 10, 3, CLAIM_FEE_BPS).unwrap(), BtcSharesValue { gross: 3, fee: 0 });
    }

    #[test]
    fn zero_fee_bps_yields_gross_only() {
        assert_eq!(sats_to_btc(50, 100, 100, 0).unwrap(), BtcSharesValue { gross: 50, fee: 0 });
    }

    #[test]
    fn zero_shares_are_worth_zero() {
        assert_eq!(sats_to_btc(0, 100, 100, CLAIM_FEE_BPS).unwrap(), BtcSharesValue { gross: 0, fee: 0 });
        // Even against an empty vault.
        assert_eq!(sats_to_btc(0, 0, 0, CLAIM_FEE_BPS).unwrap(), BtcSharesValue { gross: 0, fee: 0 });
    }

    #[test]
    fn rejects_claim_fee_above_the_bps_denominator() {
        assert!(matches!(sats_to_btc(50, 100, 100, 10_001), Err(BtcSharesValueError::InvalidClaimFeeBps)));
    }

    #[test]
    fn full_fee_withholds_the_entire_gross() {
        assert_eq!(sats_to_btc(50, 100, 100, 10_000).unwrap(), BtcSharesValue { gross: 50, fee: 50 });
    }

    #[test]
    fn rejects_overdraw() {
        assert!(matches!(sats_to_btc(101, 100, 100, CLAIM_FEE_BPS), Err(BtcSharesValueError::InsufficientShares)));
        // Any nonzero claim against an empty vault is an overdraw.
        assert!(matches!(sats_to_btc(1, 5, 0, CLAIM_FEE_BPS), Err(BtcSharesValueError::InsufficientShares)));
    }

    #[test]
    fn handles_max_values_without_overflow() {
        // shares == vault_shares at u64::MAX: gross is the whole vault.
        let max = u64::MAX;
        let value = sats_to_btc(max, max, max, CLAIM_FEE_BPS).unwrap();
        assert_eq!(value.gross, max);
    }

    #[test]
    fn first_deposit_mints_one_to_one() {
        assert_eq!(btc_to_sats(100, 0, 0).unwrap(), 100);
        // Residual BTC left by a full drain doesn't change the 1:1 reseed rate.
        assert_eq!(btc_to_sats(10, 5, 0).unwrap(), 10);
    }

    #[test]
    fn later_deposit_mints_at_exchange_rate_and_floors() {
        // 55 BTC / 50 shares (rate 1.1): 11 BTC -> 11 * 50 / 55 = 10 shares,
        // matching the on-chain deposit.
        assert_eq!(btc_to_sats(11, 55, 50).unwrap(), 10);
        // 10 BTC -> floor(10 * 50 / 55) = 9 shares.
        assert_eq!(btc_to_sats(10, 55, 50).unwrap(), 9);
    }

    #[test]
    fn zero_deposit_mints_zero_shares() {
        assert_eq!(btc_to_sats(0, 100, 100).unwrap(), 0);
        assert_eq!(btc_to_sats(0, 0, 0).unwrap(), 0);
    }

    #[test]
    fn errors_where_on_chain_math_fails() {
        // Shares issued against no BTC: division by zero on-chain.
        assert!(matches!(btc_to_sats(1, 0, 100), Err(BtcToSatsError::MathOverflow)));
        // Result exceeds u64: MAX BTC at a 2-shares-per-BTC rate.
        assert!(matches!(btc_to_sats(u64::MAX, 1, 2), Err(BtcToSatsError::MathOverflow)));
    }

    #[test]
    fn round_trips_with_sats_to_btc_at_zero_fee() {
        // Deposit into an appreciated vault, then value the minted shares
        // against the post-deposit vault state.
        let (deposit, vault_amount, vault_shares) = (11, 55, 50);
        let shares = btc_to_sats(deposit, vault_amount, vault_shares).unwrap();
        let value = sats_to_btc(shares, vault_amount + deposit, vault_shares + shares, 0).unwrap();
        assert_eq!(value.gross, deposit);
    }
}