SnapshotMap

A SnapshotMap is a key-value store like Map. It's worth familiarizing yourself with the Map type first, as everything we talked about there is applicable to SnapshotMap.

On top of that, SnapshotMap makes it a little simpler to maintain a history of values at various block heights. This involves saving "checkpoints" at some points in time - just how that is done is decided by the Strategy (opens in a new tab) type passed to the SnapshotMap constructor.

Strategy

There are currently 3 built-in strategies, although in the future this might be open to extension.

EveryBlock - a checkpoint is (conceptually) added at the beginning of every block, and historical data is available for any height
Never - there's never a checkpoint saved, and the SnapshotMap is no different from a regular Map in terms of features. Any call to may_load_at_height (opens in a new tab) will return StdError::NotFound
Selected - the add_checkpoint (opens in a new tab) method has to be called manually to add a checkpoint at the given height. Keep in mind that when calling may_load_at_height (opens in a new tab) later, the height has to be the same as the one passed to add_checkpoint (opens in a new tab). If you try to load a value at a height when no checkpoint was saved, the method will return StdError::NotFound (opens in a new tab).

Usage examples

Maintaining price histories for various trading pairs

💡

The constructor of SnapshotMap takes 3 "namespace" arguments: - the main namespace, similar to the Map constructor - two additional unique namespaces, which are used to store the changelog metadata

use cw_storage_plus::{SnapshotMap, Strategy};
 
let price: SnapshotMap<(&str, &str), Decimal> = SnapshotMap::new("p", "p1", "p2", Strategy::EveryBlock);
 
price
    .save(&mut storage, ("OSMO", "ATOM"), &Decimal::percent(81), env.block.height)
    .unwrap();
 
advance_height(&mut env, 50); // fast forward 50 blocks
 
price
    .save(&mut storage, ("OSMO", "ATOM"), &Decimal::percent(92), env.block.height)
    .unwrap();
 
// Before/at the first save, the price was unknown (uninitialized state)
assert_eq!(
    price
        .may_load_at_height(&storage, ("OSMO", "ATOM"), env.block.height - 60)
        .unwrap(),
    None
);
assert_eq!(
    price
        .may_load_at_height(&storage, ("OSMO", "ATOM"), env.block.height - 50)
        .unwrap(),
    None
);
 
// Before/at the current block, the price was 0.81
assert_eq!(
    price
        .may_load_at_height(&storage, ("OSMO", "ATOM"), env.block.height - 49)
        .unwrap(),
    Some(Decimal::percent(81))
);
assert_eq!(
    price
        .may_load_at_height(&storage, ("OSMO", "ATOM"), env.block.height)
        .unwrap(),
    Some(Decimal::percent(81))
);
 
// After the current block, the price will come up as 0.92
assert_eq!(
    price
        .may_load_at_height(&storage, ("OSMO", "ATOM"), env.block.height + 1)
        .unwrap(),
    Some(Decimal::percent(92))
);
assert_eq!(
    price
        .may_load_at_height(&storage, ("OSMO", "ATOM"),  env.block.height + 50)
        .unwrap(),
    Some(Decimal::percent(92))
);

SnapshotItem MultiTest