minibits_wallet/__tests__/onchainMeltAmounts.test.ts

/**
 * Onchain (NUT-30) melt arithmetic: fee-tier selection and the payout floor.
 *
 * Same split as the topup arithmetic tests — jest pins the pure decisions, device
 * testing covers the orchestration. What matters here is that the wallet never
 * silently spends more of the user's money on miner fees than it was asked to, and
 * never ranks fee tiers by a field that is not a rank.
 *
 * @jest-environment node
 */
import {
    findFeeOption,
    normalizeFeeOptions,
    onchainMeltFloor,
    onchainMeltTotal,
    selectDefaultFeeOption,
    MINIBITS_ONCHAIN_MELT_FLOOR_SAT,
} from '../src/services/wallet/operations/onchainAmounts'

/** cashu-ts hands `fee_reserve` over as an Amount object, not a number. */
const amount = (n: number) => ({toNumber: () => n})

describe('normalizeFeeOptions', () => {
    it('unwraps cashu-ts Amount objects into plain numbers', () => {
        const options = normalizeFeeOptions([
            {fee_index: 0, fee_reserve: amount(400), estimated_blocks: 6},
        ])
        expect(options).toEqual([{feeIndex: 0, feeReserve: 400, estimatedBlocks: 6}])
    })

    it('accepts plain numbers too', () => {
        const options = normalizeFeeOptions([
            {fee_index: 0, fee_reserve: 400, estimated_blocks: 6},
        ])
        expect(options[0].feeReserve).toBe(400)
    })

    it('sorts cheapest first', () => {
        const options = normalizeFeeOptions([
            {fee_index: 0, fee_reserve: amount(2100), estimated_blocks: 1},
            {fee_index: 1, fee_reserve: amount(400), estimated_blocks: 6},
            {fee_index: 2, fee_reserve: amount(900), estimated_blocks: 3},
        ])
        expect(options.map(o => o.feeReserve)).toEqual([400, 900, 2100])
    })

    // fee_index is the mint's IDENTIFIER for a tier, not its rank. A mint is free to
    // hand back the expensive tier as fee_index 0 — selecting by position without
    // sorting first would then pick the most expensive option as the "cheap" default.
    it('does not assume fee_index encodes the ranking', () => {
        const options = normalizeFeeOptions([
            {fee_index: 7, fee_reserve: amount(2100), estimated_blocks: 1},
            {fee_index: 3, fee_reserve: amount(400), estimated_blocks: 6},
        ])
        expect(options[0].feeIndex).toBe(3)
        expect(options[0].feeReserve).toBe(400)
    })

    it('handles an empty list without throwing', () => {
        expect(normalizeFeeOptions([])).toEqual([])
    })
})

describe('selectDefaultFeeOption', () => {
    const tiers = (...reserves: number[]) =>
        normalizeFeeOptions(
            reserves.map((r, i) => ({
                fee_index: i,
                fee_reserve: amount(r),
                estimated_blocks: reserves.length - i,
            })),
        )

    // The CDK fakewallet returns exactly one option. The picker must not ask the user
    // to choose from a list of one.
    it('returns the only option when the mint offers one tier', () => {
        const selected = selectDefaultFeeOption(tiers(400))
        expect(selected?.feeReserve).toBe(400)
    })

    it('picks the middle tier when there is a true middle', () => {
        expect(selectDefaultFeeOption(tiers(400, 900, 2100))?.feeReserve).toBe(900)
        expect(selectDefaultFeeOption(tiers(100, 200, 300, 400, 500))?.feeReserve).toBe(300)
    })

    // With an even count there is no true middle. Round DOWN: the user can always
    // choose to pay more, but a wallet must never round a fee up on their behalf.
    it('rounds to the cheaper side when there is no true middle', () => {
        expect(selectDefaultFeeOption(tiers(400, 2100))?.feeReserve).toBe(400)
        expect(selectDefaultFeeOption(tiers(100, 200, 300, 400))?.feeReserve).toBe(200)
    })

    it('is undefined when the mint returned no tiers', () => {
        // NUT-30 forbids this ("The mint MUST return at least one fee_options item"),
        // so callers treat it as a broken quote rather than inventing a fee.
        expect(selectDefaultFeeOption([])).toBeUndefined()
    })
})

describe('findFeeOption', () => {
    const options = normalizeFeeOptions([
        {fee_index: 7, fee_reserve: amount(2100), estimated_blocks: 1},
        {fee_index: 3, fee_reserve: amount(400), estimated_blocks: 6},
    ])

    it('looks a tier up by the mint\'s fee_index, not by position', () => {
        expect(findFeeOption(options, 7)?.feeReserve).toBe(2100)
        expect(findFeeOption(options, 3)?.feeReserve).toBe(400)
    })

    it('is undefined for a fee_index the mint never offered', () => {
        // The mint MUST reject a melt with an unoffered fee_index, so catching it here
        // saves a round-trip and a burned quote.
        expect(findFeeOption(options, 0)).toBeUndefined()
    })
})

describe('onchainMeltFloor', () => {
    it('applies our own floor when the mint asks for less', () => {
        expect(onchainMeltFloor('sat', 1)).toBe(MINIBITS_ONCHAIN_MELT_FLOOR_SAT)
        expect(onchainMeltFloor('sat', 546)).toBe(MINIBITS_ONCHAIN_MELT_FLOOR_SAT)
    })

    it('defers to the mint when it asks for more', () => {
        expect(onchainMeltFloor('sat', 50000)).toBe(50000)
    })

    it('applies our floor when the mint advertises nothing usable', () => {
        expect(onchainMeltFloor('sat')).toBe(MINIBITS_ONCHAIN_MELT_FLOOR_SAT)
        expect(onchainMeltFloor('sat', 0)).toBe(MINIBITS_ONCHAIN_MELT_FLOOR_SAT)
        expect(onchainMeltFloor('sat', null)).toBe(MINIBITS_ONCHAIN_MELT_FLOOR_SAT)
    })

    // The floor is denominated in sats, so it means nothing for other units.
    it('defers entirely to the mint for non-sat units', () => {
        expect(onchainMeltFloor('usd', 5)).toBe(5)
        expect(onchainMeltFloor('usd')).toBe(0)
    })

    it('clears every script type\'s dust limit', () => {
        // P2PKH dust is 546, P2WSH 330. An output below that is unspendable.
        expect(MINIBITS_ONCHAIN_MELT_FLOOR_SAT).toBeGreaterThan(546)
    })
})

describe('onchainMeltTotal', () => {
    it('is amount + fee reserve + input fee, per NUT-30', () => {
        expect(onchainMeltTotal(10000, 400, 2)).toBe(10402)
    })

    it('treats the input fee as optional', () => {
        expect(onchainMeltTotal(10000, 400)).toBe(10400)
    })
})