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 UpgradeNote,
54};
55
56mod table;
57pub use table::*;
58
59// NOTE CONSUMPTION COST
60// ================================================================================================
61
62/// Benchmarked consumption cost of a note when consumed by a network account.
63///
64/// Implemented by every priced note type in `miden-standards` and `miden-agglayer`; the values
65/// come from the generated cost tables (see the module docs).
66pub trait NoteConsumptionCost {
67 /// Cycles of the canonical network-account transaction consuming this note
68 /// (maximum across the benchmarked execution paths - an estimate, not a worst case).
69 fn consumption_cycles() -> u32;
70
71 /// Script roots of all the notes this note's consumption is expected to create.
72 ///
73 /// Where a note's outputs are chosen by its creator rather than fixed by the script (e.g. a
74 /// MINT note's recipient digest may encode any script), the list covers the typical case.
75 fn created_notes() -> Vec<NoteScriptRoot> {
76 Vec::new()
77 }
78}
79
80// NOTE COST
81// ================================================================================================
82
83/// A note's benchmarked consumption cost together with the notes its consumption creates.
84#[derive(Debug, Clone, PartialEq, Eq)]
85pub struct NoteCost {
86 cycles: u32,
87 created_notes: Vec<NoteScriptRoot>,
88}
89
90impl NoteCost {
91 /// Returns a new [`NoteCost`] from a note's consumption cycles and the script roots of the
92 /// notes its consumption creates.
93 pub fn new(cycles: u32, created_notes: Vec<NoteScriptRoot>) -> Self {
94 Self { cycles, created_notes }
95 }
96
97 /// Returns a [`NoteCost`] read from the given note type's [`NoteConsumptionCost`] impl.
98 pub fn of<N: NoteConsumptionCost>() -> Self {
99 Self::new(N::consumption_cycles(), N::created_notes())
100 }
101
102 /// Cycles of the canonical network-account transaction consuming the note (maximum across
103 /// the benchmarked execution paths - an estimate, not a worst case).
104 pub fn cycles(&self) -> u32 {
105 self.cycles
106 }
107
108 /// Script roots of the notes created when the note is consumed.
109 pub fn created_notes(&self) -> &[NoteScriptRoot] {
110 &self.created_notes
111 }
112}
113
114impl StandardNote {
115 /// Returns the benchmarked consumption cost of the standard note with the given script
116 /// root, or `None` if the root does not match a priced standard note.
117 ///
118 /// TX_FEE is not priced: it is consumed by fee-collecting operators, not by network
119 /// accounts.
120 pub fn note_cost(root: NoteScriptRoot) -> Option<NoteCost> {
121 match StandardNote::from_script_root(root)? {
122 StandardNote::P2ID => Some(NoteCost::of::<P2idNote>()),
123 StandardNote::P2IDE => Some(NoteCost::of::<P2ideNote>()),
124 StandardNote::SWAP => Some(NoteCost::of::<SwapNote>()),
125 StandardNote::PSWAP => Some(NoteCost::of::<PswapNote>()),
126 StandardNote::MINT => Some(NoteCost::of::<MintNote>()),
127 StandardNote::BURN => Some(NoteCost::of::<BurnNote>()),
128 StandardNote::CONSTANT_FEE_POLICY_CONFIG => {
129 Some(NoteCost::of::<ConstantFeePolicyConfigNote>())
130 },
131 StandardNote::FAUCET_POLICY_CONFIG => Some(NoteCost::of::<FaucetPolicyConfigNote>()),
132 StandardNote::FAUCET_METADATA_CONFIG => {
133 Some(NoteCost::of::<FaucetMetadataConfigNote>())
134 },
135 StandardNote::MIN_BURN_AMOUNT_CONFIG => Some(NoteCost::of::<MinBurnAmountConfigNote>()),
136 StandardNote::ALLOWLIST_CONFIG => Some(NoteCost::of::<AllowlistConfigNote>()),
137 StandardNote::BLOCKLIST_CONFIG => Some(NoteCost::of::<BlocklistConfigNote>()),
138 StandardNote::PAUSE_CONFIG => Some(NoteCost::of::<PauseConfigNote>()),
139 StandardNote::OWNER_CONFIG => Some(NoteCost::of::<OwnerConfigNote>()),
140 StandardNote::RBAC_CONFIG => Some(NoteCost::of::<RbacConfigNote>()),
141 StandardNote::NETWORK_ACCOUNT_CONFIG => {
142 Some(NoteCost::of::<NetworkAccountConfigNote>())
143 },
144 StandardNote::UPGRADE => Some(NoteCost::of::<UpgradeNote>()),
145 StandardNote::FEE_SPONSORSHIP => Some(NoteCost::of::<FeeSponsorshipNote>()),
146 StandardNote::TX_FEE => None,
147 }
148 }
149}
150
151// TESTS
152// ================================================================================================
153
154#[cfg(test)]
155mod tests {
156 use super::*;
157 use crate::note::TxFeeNote;
158
159 /// Pins each priced standard note's cost to its own table constant: a swap between two
160 /// note types' impls could otherwise hide inside the bench snapshot tests' 5% drift
161 /// tolerance (several constants differ by less than that).
162 #[test]
163 fn note_cost_pins_every_priced_standard_note_to_its_table_constant() {
164 for (root, expected_cycles) in [
165 (P2idNote::script_root(), P2ID_CONSUMPTION_CYCLES),
166 (P2ideNote::script_root(), P2IDE_CONSUMPTION_CYCLES),
167 (SwapNote::script_root(), SWAP_CONSUMPTION_CYCLES),
168 (PswapNote::script_root(), PSWAP_CONSUMPTION_CYCLES),
169 (MintNote::script_root(), MINT_CONSUMPTION_CYCLES),
170 (BurnNote::script_root(), BURN_CONSUMPTION_CYCLES),
171 (
172 ConstantFeePolicyConfigNote::script_root(),
173 CONSTANT_FEE_POLICY_CONFIG_CONSUMPTION_CYCLES,
174 ),
175 (FaucetPolicyConfigNote::script_root(), FAUCET_POLICY_CONFIG_CONSUMPTION_CYCLES),
176 (
177 FaucetMetadataConfigNote::script_root(),
178 FAUCET_METADATA_CONFIG_CONSUMPTION_CYCLES,
179 ),
180 (
181 MinBurnAmountConfigNote::script_root(),
182 MIN_BURN_AMOUNT_CONFIG_CONSUMPTION_CYCLES,
183 ),
184 (AllowlistConfigNote::script_root(), ALLOWLIST_CONFIG_CONSUMPTION_CYCLES),
185 (BlocklistConfigNote::script_root(), BLOCKLIST_CONFIG_CONSUMPTION_CYCLES),
186 (PauseConfigNote::script_root(), PAUSE_CONFIG_CONSUMPTION_CYCLES),
187 (OwnerConfigNote::script_root(), OWNER_CONFIG_CONSUMPTION_CYCLES),
188 (RbacConfigNote::script_root(), RBAC_CONFIG_CONSUMPTION_CYCLES),
189 (
190 NetworkAccountConfigNote::script_root(),
191 NETWORK_ACCOUNT_CONFIG_CONSUMPTION_CYCLES,
192 ),
193 (UpgradeNote::script_root(), UPGRADE_CONSUMPTION_CYCLES),
194 (FeeSponsorshipNote::script_root(), FEE_SPONSORSHIP_CONSUMPTION_CYCLES),
195 ] {
196 let cost = StandardNote::note_cost(root).expect("standard note should have a cost");
197 assert_eq!(cost.cycles(), expected_cycles);
198 }
199
200 assert!(StandardNote::note_cost(TxFeeNote::script_root()).is_none());
201 }
202}