Storage Fund Explained

/// Struct representing the storage fund, containing two `Balance`s:
/// - `total_object_storage_rebates` has the invariant that it's the sum of `storage_rebate` of
///    all objects currently stored on-chain.
/// - `non_refundable_balance` contains any remaining inflow of the storage fund that should not
///    be taken out of the fund.
public struct StorageFund has store {
    total_object_storage_rebates: Balance<SUI>,
    non_refundable_balance: Balance<SUI>,
}

public(package) fun advance_epoch(
    self: &mut StorageFund,
    storage_charges: Balance<SUI>,
    storage_fund_reinvestment: Balance<SUI>,
    leftover_staking_rewards: Balance<SUI>,
    storage_rebate_amount: u64,
    non_refundable_storage_fee_amount: u64,
): Balance<SUI> {
    // Both the reinvestment and leftover rewards are not to be refunded
    self.non_refundable_balance.join(storage_fund_reinvestment);
    self.non_refundable_balance.join(leftover_staking_rewards);

    // Storage charges go into total rebates pool
    self.total_object_storage_rebates.join(storage_charges);

    // Split out non-refundable portion of storage rebate
    let non_refundable_storage_fee = self
        .total_object_storage_rebates
        .split(non_refundable_storage_fee_amount);
    
    self.non_refundable_balance.join(non_refundable_storage_fee);

    // Return refundable portion to be burned
    let storage_rebate = self.total_object_storage_rebates.split(storage_rebate_amount);
    storage_rebate
}

User Creates Object
    ↓
  [Pay Storage Cost]
    ↓
  Storage Fund
    │
    ├─> total_object_storage_rebates (refundable)
    │
    └─> non_refundable_balance (permanent)
         ↑
         ├─ Non-refundable fees
         ├─ Staking reward overflow
         └─ Storage fund reinvestment

User Deletes Object
    ↓
  [Process Rebate]
    │
    ├─> Refund to User (most of rebate)
    │
    └─> Non-refundable fee (to fund)

public fun total_object_storage_rebates(self: &StorageFund): u64 {
    self.total_object_storage_rebates.value()
}

public fun total_balance(self: &StorageFund): u64 {
    self.total_object_storage_rebates.value() + self.non_refundable_balance.value()
}

// Create object (user pays storage)
public fun create(ctx: &mut TxContext) {
    let obj = MyObject {
        id: object::new(ctx),
        data: vector[/* 1KB of data */],
    };
    // User charged: 1024 bytes × storage_price
    // This amount held in storage fund as rebate
    transfer::transfer(obj, ctx.sender());
}

// Delete object (user gets rebate)
public fun cleanup(obj: MyObject) {
    let MyObject { id, data: _ } = obj;
    id.delete();
    // User receives: ~95% of original storage cost
    // Storage fund keeps: ~5% as non-refundable fee
}

pub struct GasCostSummary {
    pub computation_cost: u64,      // CPU/network
    pub storage_cost: u64,          // New storage
    pub storage_rebate: u64,        // Deleted storage
    pub non_refundable_storage_fee: u64,  // To storage fund
}

// Total user pays:
// computation_cost + storage_cost - storage_rebate

// Check storage cost for a transaction
const dryRun = await client.dryRunTransactionBlock({
    transactionBlock: await tx.build({ client }),
});

const gasUsed = dryRun.effects.gasUsed;
console.log('Storage cost:', gasUsed.storageCost);
console.log('Storage rebate:', gasUsed.storageRebate);
console.log('Non-refundable fee:', gasUsed.nonRefundableStorageFee);

const netStorageCost = 
    BigInt(gasUsed.storageCost) - BigInt(gasUsed.storageRebate);
console.log('Net storage cost:', netStorageCost);