feat(ICRC_Ledger): FI-1657: Export total volume counter metric for ICRC ledger (#4166)

Export a `total_volume` counter metric for the ICRC ledger.

Author: mbjorkqvist

rs/ledger_suite/icrc1/ledger/src/main.rs

@@ -84,6 +84,9 @@ thread_local! {
     static PRE_UPGRADE_INSTRUCTIONS_CONSUMED: RefCell<u64> = const { RefCell::new(0) };
     static POST_UPGRADE_INSTRUCTIONS_CONSUMED: RefCell<u64> = const { RefCell::new(0) };
     static STABLE_UPGRADE_MIGRATION_STEPS: RefCell<u64> = const { RefCell::new(0) };
+    static TOTAL_VOLUME: RefCell<f64> = const { RefCell::new(0f64) };
+    static TOTAL_VOLUME_DENOMINATOR: RefCell<f64> = const { RefCell::new(1f64) };
+    static TOTAL_VOLUME_FEE_IN_DECIMALS: RefCell<f64> = const { RefCell::new(0f64) };
 }
 
 declare_log_buffer!(name = LOG, capacity = 1000);
@@ -126,7 +129,8 @@ fn init(args: LedgerArgument) {
 
 fn init_state(init_args: InitArgs) {
     let now = TimeStamp::from_nanos_since_unix_epoch(ic_cdk::api::time());
-    LEDGER.with(|cell| *cell.borrow_mut() = Some(Ledger::from_init_args(&LOG, init_args, now)))
+    LEDGER.with(|cell| *cell.borrow_mut() = Some(Ledger::from_init_args(&LOG, init_args, now)));
+    initialize_total_volume();
 }
 
 // We use 8MiB buffer
@@ -239,6 +243,8 @@ fn post_upgrade(args: Option<LedgerArgument>) {
 
     PRE_UPGRADE_INSTRUCTIONS_CONSUMED.with(|n| *n.borrow_mut() = pre_upgrade_instructions_consumed);
 
+    initialize_total_volume();
+
     if upgrade_from_version < 3 {
         set_ledger_state(LedgerState::Migrating(LedgerField::Blocks));
         log_message(format!("Upgrading from version {upgrade_from_version} which does not store blocks in stable structures, clearing stable blocks data.").as_str());
@@ -272,6 +278,15 @@ fn post_upgrade(args: Option<LedgerArgument>) {
     POST_UPGRADE_INSTRUCTIONS_CONSUMED.with(|n| *n.borrow_mut() = instructions_consumed);
 }
 
+fn initialize_total_volume() {
+    let denominator = 10f64.powf(Access::with_ledger(|ledger| ledger.decimals()) as f64);
+    let fee = Access::with_ledger(|ledger| ledger.transfer_fee());
+    TOTAL_VOLUME_DENOMINATOR.with(|n| *n.borrow_mut() = denominator);
+    if fee != Tokens::ZERO {
+        TOTAL_VOLUME_FEE_IN_DECIMALS.with(|n| *n.borrow_mut() = tokens_to_f64(fee) / denominator);
+    }
+}
+
 fn migrate_next_part(instruction_limit: u64) {
     let instructions_migration_start = instruction_counter();
     STABLE_UPGRADE_MIGRATION_STEPS.with(|n| *n.borrow_mut() += 1);
@@ -390,6 +405,11 @@ fn encode_metrics(w: &mut ic_metrics_encoder::MetricsEncoder<Vec<u8>>) -> std::i
         stable_upgrade_migration_steps as f64,
         "Number of steps used to migrate data to stable structures.",
     )?;
+    w.encode_counter(
+        "total_volume",
+        TOTAL_VOLUME.with(|n| *n.borrow()),
+        "Total volume of ledger transactions.",
+    )?;
 
     Access::with_ledger(|ledger| {
         w.encode_gauge(
@@ -475,6 +495,50 @@ fn encode_metrics(w: &mut ic_metrics_encoder::MetricsEncoder<Vec<u8>>) -> std::i
     })
 }
 
+/// Update the total volume of token transactions. Since the total volume counter is an `f64`, it
+/// can handle large amounts, but the accuracy may suffer. Only the rate of increase of the counter
+/// should be used, since the total amount will be reset to zero each time the canister is upgraded.
+fn update_total_volume(amount: Tokens, with_fee: bool) {
+    let mut total_volume = TOTAL_VOLUME.with(|n| *n.borrow());
+    let denominator = TOTAL_VOLUME_DENOMINATOR.with(|n| *n.borrow());
+    if amount != Tokens::ZERO {
+        let amount = tokens_to_f64(amount) / denominator;
+        total_volume = f64_saturating_add(total_volume, amount);
+    }
+    if with_fee {
+        total_volume = f64_saturating_add(
+            total_volume,
+            TOTAL_VOLUME_FEE_IN_DECIMALS.with(|n| *n.borrow()),
+        );
+    }
+    TOTAL_VOLUME.with(|n| *n.borrow_mut() = total_volume);
+}
+
+fn f64_saturating_add(a: f64, b: f64) -> f64 {
+    let sum = a + b;
+
+    if sum.is_infinite() && sum.is_sign_positive() {
+        // If positive infinity, clamp to f64::MAX
+        f64::MAX
+    } else if sum.is_infinite() && sum.is_sign_negative() {
+        // If negative infinity, clamp to f64::MIN
+        f64::MIN
+    } else {
+        // Otherwise, return the regular sum
+        sum
+    }
+}
+
+#[cfg(not(feature = "u256-tokens"))]
+fn tokens_to_f64(tokens: Tokens) -> f64 {
+    tokens.to_u64() as f64
+}
+
+#[cfg(feature = "u256-tokens")]
+fn tokens_to_f64(tokens: Tokens) -> f64 {
+    tokens.to_u256().as_f64()
+}
+
 #[query(hidden = true, decoding_quota = 10000)]
 fn http_request(req: HttpRequest) -> HttpResponse {
     if req.path() == "/metrics" {
@@ -685,6 +749,7 @@ fn execute_transfer_not_async(
         };
 
         let (block_idx, _) = apply_transaction(ledger, tx, now, effective_fee)?;
+        update_total_volume(amount, effective_fee != Tokens::zero());
         Ok(block_idx)
     })
 }
@@ -900,6 +965,8 @@ fn icrc2_approve_not_async(caller: Principal, arg: ApproveArgs) -> Result<u64, A
         Ok(block_idx)
     })?;
 
+    update_total_volume(Tokens::zero(), true);
+
     Ok(block_idx)
 }
 

rs/ledger_suite/icrc1/ledger/tests/tests.rs

@@ -209,7 +209,7 @@ fn encode_init_args(args: ic_ledger_suite_state_machine_tests::InitArgs) -> Ledg
         minting_account: MINTER,
         fee_collector_account: args.fee_collector_account,
         initial_balances: args.initial_balances,
-        transfer_fee: FEE.into(),
+        transfer_fee: args.transfer_fee,
         token_name: TOKEN_NAME.to_string(),
         decimals: Some(DECIMAL_PLACES),
         token_symbol: TOKEN_SYMBOL.to_string(),
@@ -872,6 +872,14 @@ mod metrics {
             encode_upgrade_args,
         );
     }
+
+    #[test]
+    fn should_compute_and_export_total_volume_metric() {
+        ic_ledger_suite_state_machine_tests::metrics::should_compute_and_export_total_volume_metric(
+            ledger_wasm(),
+            encode_init_args,
+        );
+    }
 }
 
 // Validate upgrade of the Ledger from previous versions

rs/ledger_suite/tests/sm-tests/src/metrics.rs

@@ -1,9 +1,14 @@
-use crate::{setup, transfer, InitArgs, ARCHIVE_TRIGGER_THRESHOLD, MINTER, NUM_BLOCKS_TO_ARCHIVE};
+use crate::{
+    default_approve_args, init_args, send_approval, setup, transfer, InitArgs,
+    ARCHIVE_TRIGGER_THRESHOLD, DECIMAL_PLACES, MINTER, NUM_BLOCKS_TO_ARCHIVE,
+};
 use candid::{CandidType, Decode, Encode, Principal};
 use ic_base_types::{CanisterId, PrincipalId};
 use ic_canisters_http_types::{HttpRequest, HttpResponse};
 use ic_state_machine_tests::StateMachine;
 use ic_types::ingress::WasmResult;
+use icrc_ledger_types::icrc2::approve::ApproveArgs;
+use std::str::FromStr;
 
 pub enum LedgerSuiteType {
     ICP,
@@ -157,6 +162,127 @@ pub fn assert_ledger_upgrade_instructions_consumed_metric_set<T, U>(
     );
 }
 
+pub fn should_compute_and_export_total_volume_metric<T>(
+    ledger_wasm: Vec<u8>,
+    encode_init_args: fn(InitArgs) -> T,
+) where
+    T: CandidType,
+{
+    const TOTAL_VOLUME_METRIC: &str = "total_volume";
+    let mut expected_total = 0f64;
+
+    let initial_balances = vec![(
+        PrincipalId::new_user_test_id(1).0.into(),
+        u64::MAX - 10_000_000,
+    )];
+    let env = StateMachine::new();
+
+    let transfer_fee = 10f64.powf(DECIMAL_PLACES as f64 - 1f64) as u64;
+    println!("transfer_fee: {}", transfer_fee);
+    let args = InitArgs {
+        transfer_fee: transfer_fee.into(),
+        ..init_args(initial_balances)
+    };
+    let args = Encode!(&encode_init_args(args)).unwrap();
+    let canister_id = env.install_canister(ledger_wasm, args, None).unwrap();
+
+    let denominator = 10f64.powf(DECIMAL_PLACES as f64);
+
+    let mut increase_expected_total_volume_and_assert = |amount: u64| {
+        expected_total += amount as f64 / denominator;
+        assert_eq!(
+            format!("{:.0}", expected_total),
+            format!(
+                "{:.0}",
+                parse_metric(&env, canister_id, TOTAL_VOLUME_METRIC)
+            )
+        );
+    };
+
+    // Verify the metric returns 0 when no transactions have occurred
+    assert_eq!(0, parse_metric(&env, canister_id, TOTAL_VOLUME_METRIC));
+
+    // Perform a bunch of small transfers to verify that the computation of decimals is correct,
+    // and so that the total fee exceeds 1.0.
+    let num_operations = denominator as u64 / transfer_fee;
+    println!("performing {} transfers", num_operations);
+    for _ in 0..num_operations {
+        transfer(
+            &env,
+            canister_id,
+            PrincipalId::new_user_test_id(1).0,
+            PrincipalId::new_user_test_id(2).0,
+            transfer_fee,
+        )
+        .expect("transfer failed");
+    }
+    increase_expected_total_volume_and_assert(2 * num_operations * transfer_fee);
+
+    // Verify total volume accounting handles minting correctly (no fee).
+    for _ in 0..num_operations {
+        transfer(
+            &env,
+            canister_id,
+            MINTER,
+            PrincipalId::new_user_test_id(1).0,
+            transfer_fee,
+        )
+        .expect("mint failed");
+    }
+    increase_expected_total_volume_and_assert(num_operations * transfer_fee);
+
+    // Verify total volume accounting handles burning correctly (no fee).
+    for _ in 0..num_operations {
+        transfer(
+            &env,
+            canister_id,
+            PrincipalId::new_user_test_id(1).0,
+            MINTER,
+            transfer_fee,
+        )
+        .expect("burn failed");
+    }
+    increase_expected_total_volume_and_assert(num_operations * transfer_fee);
+
+    // Verify total volume accounting handles approvals correctly (no amount).
+    let approve_args = ApproveArgs {
+        fee: Some(transfer_fee.into()),
+        ..default_approve_args(PrincipalId::new_user_test_id(1).0, 1_000_000_000)
+    };
+    for _ in 0..num_operations {
+        send_approval(
+            &env,
+            canister_id,
+            PrincipalId::new_user_test_id(2).0,
+            &approve_args,
+        )
+        .expect("approval failed");
+    }
+    increase_expected_total_volume_and_assert(num_operations * transfer_fee);
+
+    // Perform some larger transfers to verify a total volume larger than u64::MAX is handled correctly.
+    transfer(
+        &env,
+        canister_id,
+        PrincipalId::new_user_test_id(1).0,
+        PrincipalId::new_user_test_id(2).0,
+        u64::MAX - 1_000_000_000,
+    )
+    .expect("transfer failed");
+    increase_expected_total_volume_and_assert(u64::MAX - 1_000_000_000 + transfer_fee);
+
+    transfer(
+        &env,
+        canister_id,
+        PrincipalId::new_user_test_id(2).0,
+        PrincipalId::new_user_test_id(1).0,
+        u64::MAX - 10_000_000_000,
+    )
+    .expect("transfer failed");
+
+    increase_expected_total_volume_and_assert(u64::MAX - 10_000_000_000 + transfer_fee);
+}
+
 fn assert_existence_of_metric(env: &StateMachine, canister_id: CanisterId, metric: &str) {
     let metrics = retrieve_metrics(env, canister_id);
     assert!(
@@ -180,9 +306,10 @@ pub fn parse_metric(env: &StateMachine, canister_id: CanisterId, metric: &str) -
         let value_str = *tokens
             .get(1)
             .unwrap_or_else(|| panic!("metric line '{}' should have at least two tokens", line));
-        return value_str
-            .parse()
-            .unwrap_or_else(|err| panic!("metric value is not an integer: {} ({})", line, err));
+        let u64_value = f64::from_str(value_str)
+            .unwrap_or_else(|err| panic!("metric value is not an number: {} ({})", line, err))
+            .round() as u64;
+        return u64_value;
     }
     panic!("metric '{}' not found in metrics: {:?}", metric, metrics);
 }