sui_sdk_types/
gas.rs

1/// Summary of gas charges.
2///
3/// Storage is charged independently of computation.
4/// There are 3 parts to the storage charges:
5/// `storage_cost`: it is the charge of storage at the time the transaction is executed.
6///                 The cost of storage is the number of bytes of the objects being mutated
7///                 multiplied by a variable storage cost per byte
8/// `storage_rebate`: this is the amount a user gets back when manipulating an object.
9///                   The `storage_rebate` is the `storage_cost` for an object minus fees.
10/// `non_refundable_storage_fee`: not all the value of the object storage cost is
11///                               given back to user and there is a small fraction that
12///                               is kept by the system. This value tracks that charge.
13///
14/// When looking at a gas cost summary the amount charged to the user is
15/// `computation_cost + storage_cost - storage_rebate`
16/// and that is the amount that is deducted from the gas coins.
17/// `non_refundable_storage_fee` is collected from the objects being mutated/deleted
18/// and it is tracked by the system in storage funds.
19///
20/// Objects deleted, including the older versions of objects mutated, have the storage field
21/// on the objects added up to a pool of "potential rebate". This rebate then is reduced
22/// by the "nonrefundable rate" such that:
23/// `potential_rebate(storage cost of deleted/mutated objects) =
24/// storage_rebate + non_refundable_storage_fee`
25///
26/// # BCS
27///
28/// The BCS serialized form for this type is defined by the following ABNF:
29///
30/// ```text
31/// gas-cost-summary = u64 ; computation-cost
32///                    u64 ; storage-cost
33///                    u64 ; storage-rebate
34///                    u64 ; non-refundable-storage-fee
35/// ```
36#[derive(Clone, Debug, Default, PartialEq, Eq)]
37#[cfg_attr(
38    feature = "serde",
39    derive(serde_derive::Serialize, serde_derive::Deserialize)
40)]
41#[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
42pub struct GasCostSummary {
43    /// Cost of computation/execution
44    pub computation_cost: u64,
45
46    /// Storage cost, it's the sum of all storage cost for all objects created or mutated.
47    pub storage_cost: u64,
48
49    /// The amount of storage cost refunded to the user for all objects deleted or mutated in the
50    /// transaction.
51    pub storage_rebate: u64,
52
53    /// The fee for the rebate. The portion of the storage rebate kept by the system.
54    pub non_refundable_storage_fee: u64,
55}
56
57impl GasCostSummary {
58    /// Create a new gas cost summary.
59    ///
60    /// # Arguments
61    /// * `computation_cost` - Cost of computation cost/execution.
62    /// * `storage_cost` - Storage cost, it's the sum of all storage cost for all objects created or mutated.
63    /// * `storage_rebate` - The amount of storage cost refunded to the user for all objects deleted or mutated in the transaction.
64    /// * `non_refundable_storage_fee` - The fee for the rebate. The portion of the storage rebate kept by the system.
65    pub fn new(
66        computation_cost: u64,
67        storage_cost: u64,
68        storage_rebate: u64,
69        non_refundable_storage_fee: u64,
70    ) -> GasCostSummary {
71        GasCostSummary {
72            computation_cost,
73            storage_cost,
74            storage_rebate,
75            non_refundable_storage_fee,
76        }
77    }
78
79    /// The total gas used, which is the sum of computation and storage costs.
80    pub fn gas_used(&self) -> u64 {
81        self.computation_cost + self.storage_cost
82    }
83
84    /// The net gas usage, which is the total gas used minus the storage rebate.
85    /// A positive number means used gas; negative number means refund.
86    pub fn net_gas_usage(&self) -> i64 {
87        self.gas_used() as i64 - self.storage_rebate as i64
88    }
89}
90
91impl std::fmt::Display for GasCostSummary {
92    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
93        write!(f, "computation_cost: {}, ", self.computation_cost)?;
94        write!(f, "storage_cost: {}, ", self.storage_cost)?;
95        write!(f, "storage_rebate: {}, ", self.storage_rebate)?;
96        write!(
97            f,
98            "non_refundable_storage_fee: {}",
99            self.non_refundable_storage_fee
100        )
101    }
102}
103
104#[cfg(test)]
105mod test {
106    use super::*;
107
108    #[cfg(target_arch = "wasm32")]
109    use wasm_bindgen_test::wasm_bindgen_test as test;
110
111    #[test]
112    #[cfg(feature = "serde")]
113    fn formats() {
114        let actual = GasCostSummary {
115            computation_cost: 42,
116            storage_cost: u64::MAX,
117            storage_rebate: 0,
118            non_refundable_storage_fee: 9,
119        };
120
121        println!("{}", serde_json::to_string(&actual).unwrap());
122        println!("{:?}", bcs::to_bytes(&actual).unwrap());
123    }
124}
sui_sdk_types/gas.rs

sui_sdk_types/
gas.rs
