Gas Mechanism and Pricing

pub struct GasCostSummary {
    /// Cost of computation/execution
    pub computation_cost: u64,
    /// Storage cost, it's the sum of all storage cost for all objects created or mutated
    pub storage_cost: u64,
    /// The amount of storage cost refunded to the user for all objects deleted or mutated
    pub storage_rebate: u64,
    /// The fee for the rebate. The portion of the storage rebate kept by the system
    pub non_refundable_storage_fee: u64,
}

Total Gas Charged = computation_cost + storage_cost - storage_rebate

pub fn new(
    gas_budget: u64,
    gas_price: u64,
    reference_gas_price: u64,
    config: &ProtocolConfig,
) -> SuiResult<Self> {
    // gas price must be bigger or equal to reference gas price
    if gas_price < reference_gas_price {
        return Err(UserInputError::GasPriceUnderRGP {
            gas_price,
            reference_gas_price,
        }
        .into());
    }
    if check_for_gas_price_too_high(config.gas_model_version())
        && gas_price >= config.max_gas_price()
    {
        return Err(UserInputError::GasPriceTooHigh {
            max_gas_price: config.max_gas_price(),
        }
        .into());
    }
    // ...
}

pub const TEST_ONLY_GAS_UNIT_FOR_TRANSFER: u64 = 10_000;
pub const TEST_ONLY_GAS_UNIT_FOR_OBJECT_BASICS: u64 = 50_000;
pub const TEST_ONLY_GAS_UNIT_FOR_PUBLISH: u64 = 70_000;
pub const TEST_ONLY_GAS_UNIT_FOR_STAKING: u64 = 50_000;
pub const TEST_ONLY_GAS_UNIT_FOR_GENERIC: u64 = 50_000;
pub const TEST_ONLY_GAS_UNIT_FOR_SPLIT_COIN: u64 = 10_000;
pub const TEST_ONLY_GAS_UNIT_FOR_HEAVY_COMPUTATION_STORAGE: u64 = 5_000_000;

storage_cost = object_size_bytes * storage_price_per_byte

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> {
    // Join reinvestment and leftover rewards to non-refundable balance
    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
    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
    let storage_rebate = self.total_object_storage_rebates.split(storage_rebate_amount);
    storage_rebate
}

const tx = new Transaction();
tx.setGasBudget(10_000_000); // 10M gas units

// Bad: Large object size
public struct BadNFT has key {
    id: UID,
    full_image: vector<u8>,  // 10 MB image data
    metadata: LargeStruct,    // Redundant data
}

// Good: Minimal on-chain storage
public struct GoodNFT has key {
    id: UID,
    image_url: String,        // Reference to off-chain storage
    essential_data: u64,      // Only critical data on-chain
}

// Bad: Multiple transactions
for (const recipient of recipients) {
    const tx = new Transaction();
    tx.transferObjects([coin], recipient);
    await client.signAndExecuteTransaction({ transaction: tx, signer });
}

// Good: Single transaction with multiple operations
const tx = new Transaction();
for (const recipient of recipients) {
    const [coin] = tx.splitCoins(tx.gas, [amount]);
    tx.transferObjects([coin], recipient);
}
await client.signAndExecuteTransaction({ transaction: tx, signer });

// Bad: Vector requires linear search
public struct Registry has key {
    id: UID,
    items: vector<Item>,  // O(n) lookup
}

// Good: Table provides O(1) lookup
public struct Registry has key {
    id: UID,
    items: Table<ID, Item>,  // O(1) lookup
}

public fun cleanup(old_obj: TempObject) {
    let TempObject { id, .. } = old_obj;
    id.delete();  // Recover storage rebate
}

const tx = new Transaction();
// ... build transaction

const dryRun = await client.dryRunTransactionBlock({
    transactionBlock: await tx.build({ client }),
});

const gasUsed = dryRun.effects.gasUsed;
console.log('Computation:', gasUsed.computationCost);
console.log('Storage:', gasUsed.storageCost);
console.log('Rebate:', gasUsed.storageRebate);
console.log('Total:', 
    BigInt(gasUsed.computationCost) + 
    BigInt(gasUsed.storageCost) - 
    BigInt(gasUsed.storageRebate)
);

const result = await client.getTransactionBlock({
    digest: 'transaction_digest',
    options: { showEffects: true },
});

const gas = result.effects!.gasUsed;
console.log('Gas summary:', gas);

pub fn new_unmetered() -> Self {
    Self::V2(SuiGasStatusV2::new_unmetered())
}

/// Return the `value: u64` field of a `Coin<T>` type.
/// Useful for reading the coin without deserializing the object into a Move value
pub fn get_coin_value_unsafe(&self) -> u64 {
    debug_assert!(self.type_.is_coin());
    // 32 bytes for object ID, 8 for balance
    debug_assert!(self.contents.len() == 40);
    u64::from_le_bytes(<[u8; 8]>::try_from(&self.contents[ID_END_INDEX..]).unwrap())
}

/// Update the `value: u64` field of a `Coin<T>` type.
pub fn set_coin_value_unsafe(&mut self, value: u64) {
    debug_assert!(self.type_.is_coin());
    // 32 bytes for object ID, 8 for balance
    debug_assert!(self.contents.len() == 40);
    self.contents.splice(ID_END_INDEX.., value.to_le_bytes());
}