miden_standards/note/costs/mod.rs
1//! Benchmarked consumption costs of the standard notes, and helpers turning them into fees.
2//!
3//! Each constant is the number of VM cycles of the canonical network-account transaction
4//! consuming the note, measured by the `bench-transaction` binary: an account authenticated
5//! with [`AuthNetworkAccount`](crate::account::auth::AuthNetworkAccount) (carrying the
6//! components the note requires) consumes the note on a fee-charging chain, so the measured
7//! cycles include the allowlist checks and TX_FEE note creation.
8//!
9//! The values are denominated in cycles rather than fee units, since the fee
10//! (`verification_base_fee * (ilog2(cycles) + 1)`) depends on a block-header parameter. Use
11//! the `NetworkNotePricer` in `miden-tx` to turn cycle costs into concrete fees and populate a
12//! fee schedule via
13//! [`BasicConstantFeePolicy::with_fees`](crate::account::fees::BasicConstantFeePolicy::with_fees).
14//!
15//! The values are estimates from canonical scenarios, not worst cases: asset-scaling paths
16//! carry 16 callback-free assets (the maximum per note) and action notes exercise a single
17//! note variant, so callback-carrying notes can exceed the values - do not treat them as
18//! guaranteed fee upper bounds.
19//!
20//! Terminology: a note's *cost* is its measured cycle count; its *price* is the fee derived
21//! from that cost (and from the costs of the notes its consumption creates).
22//!
23//! The table is regenerated with `make update-note-costs`; a snapshot test in
24//! `bench-transaction` fails CI when a checked-in value drifts more than 5% from the measured
25//! one (small drift from unrelated changes is tolerated - the pricing safety margin dwarfs
26//! it).
27
28use alloc::vec::Vec;
29
30use miden_protocol::note::NoteScriptRoot;
31
32use crate::note::config::{
33 AllowlistConfigNote,
34 BlocklistConfigNote,
35 ConstantFeePolicyConfigNote,
36 FaucetMetadataConfigNote,
37 FaucetPolicyConfigNote,
38 MinBurnAmountConfigNote,
39 NetworkAccountConfigNote,
40 OwnerConfigNote,
41 PauseConfigNote,
42 RbacConfigNote,
43};
44use crate::note::{
45 BurnNote,
46 FeeSponsorshipNote,
47 MintNote,
48 P2idNote,
49 P2ideNote,
50 PswapNote,
51 StandardNote,
52 SwapNote,
53};
54
55mod table;
56pub use table::*;
57
58// NOTE CONSUMPTION COST
59// ================================================================================================
60
61/// Benchmarked consumption cost of a note when consumed by a network account.
62///
63/// Implemented by every priced note type in `miden-standards` and `miden-agglayer`; the values
64/// come from the generated cost tables (see the module docs).
65pub trait NoteConsumptionCost {
66 /// Cycles of the canonical network-account transaction consuming this note
67 /// (maximum across the benchmarked execution paths - an estimate, not a worst case).
68 fn consumption_cycles() -> u32;
69
70 /// Script roots of all the notes this note's consumption is expected to create.
71 ///
72 /// Where a note's outputs are chosen by its creator rather than fixed by the script (e.g. a
73 /// MINT note's recipient digest may encode any script), the list covers the typical case.
74 fn created_notes() -> Vec<NoteScriptRoot> {
75 Vec::new()
76 }
77}
78
79// NOTE COST
80// ================================================================================================
81
82/// A note's benchmarked consumption cost together with the notes its consumption creates.
83#[derive(Debug, Clone, PartialEq, Eq)]
84pub struct NoteCost {
85 cycles: u32,
86 created_notes: Vec<NoteScriptRoot>,
87}
88
89impl NoteCost {
90 /// Returns a new [`NoteCost`] from a note's consumption cycles and the script roots of the
91 /// notes its consumption creates.
92 pub fn new(cycles: u32, created_notes: Vec<NoteScriptRoot>) -> Self {
93 Self { cycles, created_notes }
94 }
95
96 /// Returns a [`NoteCost`] read from the given note type's [`NoteConsumptionCost`] impl.
97 pub fn of<N: NoteConsumptionCost>() -> Self {
98 Self::new(N::consumption_cycles(), N::created_notes())
99 }
100
101 /// Cycles of the canonical network-account transaction consuming the note (maximum across
102 /// the benchmarked execution paths - an estimate, not a worst case).
103 pub fn cycles(&self) -> u32 {
104 self.cycles
105 }
106
107 /// Script roots of the notes created when the note is consumed.
108 pub fn created_notes(&self) -> &[NoteScriptRoot] {
109 &self.created_notes
110 }
111}
112
113impl StandardNote {
114 /// Returns the benchmarked consumption cost of the standard note with the given script
115 /// root, or `None` if the root does not match a priced standard note.
116 ///
117 /// TX_FEE is not priced: it is consumed by fee-collecting operators, not by network
118 /// accounts.
119 pub fn note_cost(root: NoteScriptRoot) -> Option<NoteCost> {
120 match StandardNote::from_script_root(root)? {
121 StandardNote::P2ID => Some(NoteCost::of::<P2idNote>()),
122 StandardNote::P2IDE => Some(NoteCost::of::<P2ideNote>()),
123 StandardNote::SWAP => Some(NoteCost::of::<SwapNote>()),
124 StandardNote::PSWAP => Some(NoteCost::of::<PswapNote>()),
125 StandardNote::MINT => Some(NoteCost::of::<MintNote>()),
126 StandardNote::BURN => Some(NoteCost::of::<BurnNote>()),
127 StandardNote::CONSTANT_FEE_POLICY_CONFIG => {
128 Some(NoteCost::of::<ConstantFeePolicyConfigNote>())
129 },
130 StandardNote::FAUCET_POLICY_CONFIG => Some(NoteCost::of::<FaucetPolicyConfigNote>()),
131 StandardNote::FAUCET_METADATA_CONFIG => {
132 Some(NoteCost::of::<FaucetMetadataConfigNote>())
133 },
134 StandardNote::MIN_BURN_AMOUNT_CONFIG => Some(NoteCost::of::<MinBurnAmountConfigNote>()),
135 StandardNote::ALLOWLIST_CONFIG => Some(NoteCost::of::<AllowlistConfigNote>()),
136 StandardNote::BLOCKLIST_CONFIG => Some(NoteCost::of::<BlocklistConfigNote>()),
137 StandardNote::PAUSE_CONFIG => Some(NoteCost::of::<PauseConfigNote>()),
138 StandardNote::OWNER_CONFIG => Some(NoteCost::of::<OwnerConfigNote>()),
139 StandardNote::RBAC_CONFIG => Some(NoteCost::of::<RbacConfigNote>()),
140 StandardNote::NETWORK_ACCOUNT_CONFIG => {
141 Some(NoteCost::of::<NetworkAccountConfigNote>())
142 },
143 StandardNote::FEE_SPONSORSHIP => Some(NoteCost::of::<FeeSponsorshipNote>()),
144 StandardNote::TX_FEE => None,
145 }
146 }
147}
148
149// TESTS
150// ================================================================================================
151
152#[cfg(test)]
153mod tests {
154 use super::*;
155 use crate::note::TxFeeNote;
156
157 /// Pins each priced standard note's cost to its own table constant: a swap between two
158 /// note types' impls could otherwise hide inside the bench snapshot tests' 5% drift
159 /// tolerance (several constants differ by less than that).
160 #[test]
161 fn note_cost_pins_every_priced_standard_note_to_its_table_constant() {
162 for (root, expected_cycles) in [
163 (P2idNote::script_root(), P2ID_CONSUMPTION_CYCLES),
164 (P2ideNote::script_root(), P2IDE_CONSUMPTION_CYCLES),
165 (SwapNote::script_root(), SWAP_CONSUMPTION_CYCLES),
166 (PswapNote::script_root(), PSWAP_CONSUMPTION_CYCLES),
167 (MintNote::script_root(), MINT_CONSUMPTION_CYCLES),
168 (BurnNote::script_root(), BURN_CONSUMPTION_CYCLES),
169 (
170 ConstantFeePolicyConfigNote::script_root(),
171 CONSTANT_FEE_POLICY_CONFIG_CONSUMPTION_CYCLES,
172 ),
173 (FaucetPolicyConfigNote::script_root(), FAUCET_POLICY_CONFIG_CONSUMPTION_CYCLES),
174 (
175 FaucetMetadataConfigNote::script_root(),
176 FAUCET_METADATA_CONFIG_CONSUMPTION_CYCLES,
177 ),
178 (
179 MinBurnAmountConfigNote::script_root(),
180 MIN_BURN_AMOUNT_CONFIG_CONSUMPTION_CYCLES,
181 ),
182 (AllowlistConfigNote::script_root(), ALLOWLIST_CONFIG_CONSUMPTION_CYCLES),
183 (BlocklistConfigNote::script_root(), BLOCKLIST_CONFIG_CONSUMPTION_CYCLES),
184 (PauseConfigNote::script_root(), PAUSE_CONFIG_CONSUMPTION_CYCLES),
185 (OwnerConfigNote::script_root(), OWNER_CONFIG_CONSUMPTION_CYCLES),
186 (RbacConfigNote::script_root(), RBAC_CONFIG_CONSUMPTION_CYCLES),
187 (
188 NetworkAccountConfigNote::script_root(),
189 NETWORK_ACCOUNT_CONFIG_CONSUMPTION_CYCLES,
190 ),
191 (FeeSponsorshipNote::script_root(), FEE_SPONSORSHIP_CONSUMPTION_CYCLES),
192 ] {
193 let cost = StandardNote::note_cost(root).expect("standard note should have a cost");
194 assert_eq!(cost.cycles(), expected_cycles);
195 }
196
197 assert!(StandardNote::note_cost(TxFeeNote::script_root()).is_none());
198 }
199}