Improve the type safety of contract storage

[leighmcculloch]

For sometime folks have asked for ways to improve the type safety of working with contract storage, with the main complaint being that one can mix up the key type, storage type, and the value type, writing with one type at one location and reading at another.

This issue is a starting point to start collecting storage patterns and solutions that folks are using. Post other solutions and patterns as comments. I will keep the issue description updated with a summary of all.

This issue may not result in a change to the soroban-sdk, but it may if an approach proves to meaningfully improve contract safety and the developer experience. Anything the sdk adopts should be composable and general enough to lean into the 'library' lane rather than lean into the 'framework' lane. That distinction will not always be clear.

Solutions seen in the wild:

• soroban-example's enum DataKey pattern that defines an enum for data keys, so that key reuse is more likely example cc @sisuresh

• @axelarnetwork's #[contractstorage] macro that defines a list of storage keys, and associates storage types and value types with the key docs.rs/stellar-axelar-std-derive cc @nbayindirli

• @BlaineHeffron's #[contractstorage] on a struct that translates struct fields representing stored values. BlaineHeffron/soroban-sdk-tools cc @willemneal

[leighmcculloch]

Here's an alternative approach, that came out of an analysis of the three approaches above. See the collapsed details at the bottom of this comment for the full analysis.

This is the code many developers type today:

#[contracttype]
pub enum DataKey {
    Balance(Address),
    Allowance { from: Address, spender: Address },
    Admin,
    Initialized,
}

This is the code a developer could type to increase type safety, based on the analysis below:

#[contracttype(storage)]
pub enum DataKey {
    #[storage(persistent, value = i128)]
    Balance(Address),

    #[storage(temporary, value = AllowanceValue)]
    Allowance { from: Address, spender: Address },

    #[storage(instance, value = Address)]
    Admin,

    #[storage(instance, status)]
    Initialized,
}

Generates:

pub struct DataKeyAccess<'a> { env: &'a Env }

impl DataKey {
    pub fn access(env: &Env) -> DataKeyAccess<'_> { ... }
}

impl<'a> DataKeyAccess<'a> {
    // Balance — persistent, i128
    pub fn get_balance(&self, arg0: &Address) -> i128 { ... }       // unwraps
    pub fn try_get_balance(&self, arg0: &Address) -> Option<i128> { ... }
    pub fn set_balance(&self, arg0: &Address, val: &i128) { ... }
    pub fn has_balance(&self, arg0: &Address) -> bool { ... }
    pub fn remove_balance(&self, arg0: &Address) { ... }
    pub fn update_balance(&self, arg0: &Address, f: impl FnOnce(Option<i128>) -> i128) -> i128 { ... }
    pub fn extend_ttl_balance(&self, arg0: &Address, threshold: u32, extend_to: u32) { ... }

    // Allowance — temporary, AllowanceValue (named fields → method params)
    pub fn try_get_allowance(&self, from: &Address, spender: &Address) -> Option<AllowanceValue> { ... }
    pub fn set_allowance(&self, from: &Address, spender: &Address, val: &AllowanceValue) { ... }
    // ...

    // Admin — instance, Address
    pub fn get_admin(&self) -> Address { ... }
    pub fn try_get_admin(&self) -> Option<Address> { ... }
    pub fn set_admin(&self, val: &Address) { ... }
    // ... (no per-key extend_ttl for instance)

    // Initialized — instance, status
    pub fn is_initialized(&self) -> bool { ... }
    pub fn set_initialized(&self) { ... }
    pub fn remove_initialized(&self) { ... }
}

Why:

Lowest migration cost. The enum DataKey pattern is already the community standard. Adding #[contractstorage] and #[storage(...)] attributes is additive — zero breaking changes, gradual adoption per call site.

Approach keeps the SDK composable: it doesn't take ownership of #[contracttype], doesn't force visibility constraints, doesn't bake in TTL policy. Contracts can mix typed and untyped access during migration.

---

Full Analysis

Type-Safe Contract Storage Approaches

Issue: #1762
Date: 2026-03-30

1. Background

The Soroban SDK storage API (env.storage().persistent(), .temporary(), .instance()) is fully generic: any IntoVal<Env, Val> type can be used as a key with any storage type and any value type. This flexibility means three classes of bugs compile silently:

1. Wrong storage type — e.g., writing a balance to temporary() instead of persistent(), causing silent data loss on expiry.
2. Wrong value type — e.g., reading a balance as String instead of i128, causing a runtime panic or silent None.
3. Turbofish burden — every get call requires explicit ::<K, V> annotation, with no compile-time check that call sites agree.

Three approaches to closing these gaps have been identified in the community.

2. Approach Summaries

A. Enum DataKey + #[contractstorage] (Exploration 1 — SDK-native proposal)

Source: exploration-enum-datakey.md in this repo

Annotates the existing #[contracttype] enum with a new #[contractstorage] attribute macro. Each variant declares its storage type and value type:

#[contractstorage]
#[contracttype]
pub enum DataKey {
    #[storage(persistent, value = i128)]
    Balance(Address),
    #[storage(instance, value = Address)]
    Admin,
    #[storage(temporary, value = AllowanceValue)]
    Allowance(AllowanceDataKey),
}

Generates a companion DataKeyAccess struct with typed methods: get_balance(&Address) -> Option<i128>, set_admin(&Address), etc. The raw untyped API remains available.

B. Axelar #[contractstorage] (enum-based, free functions)

Source: stellar-axelar-std-derive, axelar-cgp-soroban

Also enum-based, but generates free functions rather than an accessor struct. Uses named fields on variants instead of tuple fields, and separate #[value(Type)] / #[status] + #[persistent] / #[instance] / #[temporary] attributes:

#[contractstorage]
enum DataKey {
    #[instance]
    #[value(Address)]
    Gateway,
    #[persistent]
    #[value(String)]
    Message { sender: Address },
    #[temporary]
    #[status]
    Initialized,
}

Generates: gateway(env) -> Address, set_gateway(env, &Address), try_message(env, sender) -> Option<String>, is_initialized(env) -> bool, etc. Also generates extend_{name}_ttl functions and automatic TTL extension on persistent reads. Includes golden-file tests to detect storage schema drift.

Key difference: The enum must be private (not pub). The macro itself emits #[contracttype] on the transformed enum, so users don't write it. Named fields on variants are transformed into tuple variants in the generated #[contracttype] enum.

C. BlaineHeffron #[contractstorage] (struct-based)

Source: BlaineHeffron/soroban-sdk-tools

Uses a struct instead of an enum. Each field's type encodes the storage type and value type via phantom types like PersistentMap<K, V>, InstanceItem<V>, TemporaryMap<K, V>:

#[contractstorage]
pub struct MyStorage {
    balances: PersistentMap<Address, u64>,
    total_supply: InstanceItem<u64>,
    sessions: TemporaryMap<Address, SessionData>,
}

Generates static methods (MyStorage::get_balances(env, &key), MyStorage::set_total_supply(env, &val)) and supports instantiation (MyStorage::new(env)) for multi-field access. Includes auto_shorten key compression.

3. Comparison Matrix

Dimension	A. Enum DataKey (SDK proposal)	B. Axelar (enum, free fns)	C. BlaineHeffron (struct)
Input shape	pub enum with tuple variants	Private enum with named-field variants	pub struct with typed fields
Key type safety	Yes — variant encodes key	Yes — variant encodes key	Yes — field name is the key discriminant
Value type safety	Yes — #[storage(value = T)]	Yes — #[value(T)] or #[status]	Yes — generic param Map<K, V>, Item<V>
Storage type safety	Yes — #[storage(persistent)]	Yes — #[persistent] / etc.	Yes — PersistentMap vs InstanceItem vs TemporaryMap
Turbofish eliminated	Yes	Yes	Yes
Generated API shape	Accessor struct (DataKeyAccess)	Free functions in same scope	Static methods + instantiable struct
#[contracttype] handling	User writes it; macro strips helper attrs before #[contracttype] sees them	Macro emits #[contracttype] automatically	No enum key at all — field names become keys
Composite keys (maps)	Tuple variant fields become method params	Named variant fields become method params	Map<K, V> generic param, key passed to methods
Unit keys (singletons)	Unit variant → no params	Unit variant → env-only params	Item<V> field → no key param
TTL handling	extend_ttl_{name} with explicit threshold/extend_to	extend_{name}_ttl + auto-extend on persistent read	Not documented; likely manual
Auto TTL on read	No — explicit only	Yes — persistent reads auto-extend	No
#[status] (bool-like)	No — uses value = bool	Yes — #[status] generates is_* / set_*_status	No
try_get variant	Open question	Yes — try_{name} returns Option<T>	Returns Option<T> by default
Key compression	No	No	Yes — auto_shorten reduces fees
Schema drift detection	No	Yes — golden-file test generated	No
Enum visibility	pub allowed	Must be private	N/A (struct)
Raw API bypass	Still available	Still available	Still available
Compile-time enforcement	All three safety gaps closed	All three safety gaps closed	All three safety gaps closed
Runtime overhead	Zero — delegates to same storage calls	Zero	Zero
Migration cost	Minimal — add attr to existing enum	Moderate — rewrite variants to named fields, make private	High — rewrite enum to struct, new type imports
Existing pattern alignment	High — mirrors soroban-examples convention	Medium — same enum concept, different syntax	Low — completely different mental model
Library vs. framework feel	Library — opt-in, composable	Leans framework — auto-TTL, forced privacy, owns #[contracttype]	Library — opt-in types
Ecosystem dependency	None (SDK-native)	stellar-axelar-std	soroban-sdk-tools

4. Detailed Analysis

4.1 Type Safety (all three close the same gaps)

All three approaches achieve the same core outcome: associating key → value type → storage type at compile time. The mechanism differs (attribute annotation vs. phantom types), but the safety guarantees are equivalent. None can prevent bypass via the raw env.storage() API.

4.2 Ergonomics

Approach A wins on migration ergonomics: the existing enum DataKey pattern from soroban-examples is the de facto standard. Adding #[contractstorage] and #[storage(...)] attributes is the smallest syntactic delta. The accessor struct provides IDE-friendly autocomplete via DataKey::access(&env).get_*.

Approach B is slightly more opinionated (forced private visibility, auto-TTL, #[status] sugar, golden-file tests). These are useful features but impose decisions that may not suit all contracts. The try_* vs unwrapping * getter split is a good ergonomic choice.

Approach C offers the cleanest "data declaration" feel — PersistentMap<Address, u64> reads like a type definition. However, it abandons the enum key pattern entirely, which means: (a) the storage key encoding is implicit in field names rather than explicit enum discriminants, (b) existing contracts must be fully rewritten, and (c) it's harder to see the raw serialized key shape.

4.3 Composability and Library Fit

The issue description emphasizes that anything adopted should "lean into the 'library' lane rather than the 'framework' lane."

• A is the most library-like: opt-in annotation on existing types, no opinions about TTL policy, no forced visibility, no auto-generated tests.
• B crosses into framework territory: it takes ownership of #[contracttype] emission, forces private enums, bakes in TTL policy (auto-extend on persistent read), and generates test modules.
• C is library-like in principle (opt-in struct types), but the complete departure from the enum key pattern makes it harder to compose with contracts that mix raw and typed access during migration.

4.4 Complex Patterns

Maps with composite keys: All three handle this. A uses tuple variant fields, B uses named variant fields (arguably more readable), C uses Map<K, V> generics.

Multiple independent storage schemas: A supports multiple enums trivially. B requires multiple private enums. C naturally supports multiple structs.

Cross-contract key sharing: A preserves the pub enum for external visibility. B's forced-private enum complicates sharing. C's struct fields are not directly shareable as serialized keys.

TTL management: B's auto-extend is convenient but opinionated. A and C leave TTL explicit, which is more flexible but more verbose.

4.5 Key Compression

C's auto_shorten is a unique and valuable feature — shorter keys reduce storage fees. This is orthogonal to type safety and could be adopted independently.

5. Hybrid Viability

A hybrid combining the best elements is viable and recommended:

Element	Source	Rationale
Enum-based input with #[contractstorage]	A	Aligns with existing ecosystem convention; lowest migration cost
Named fields on variants	B	More readable than positional tuple fields for composite keys
Accessor struct (not free functions)	A	Better IDE discoverability, natural grouping, can be passed around
try_get / get split	B	try_* returns Option, * unwraps — covers both use cases
#[status] sugar	B	Clean ergonomics for boolean flags (is_initialized)
Explicit TTL (no auto-extend)	A	Library-like; TTL policy is operational, not schema
User controls #[contracttype]	A	Don't take ownership of another macro's responsibilities
pub enum allowed	A	Needed for cross-contract key sharing
Schema drift golden-file tests	B	Optional/opt-in — valuable for production contracts
Key compression	C	Orthogonal feature; could be a separate #[contractstorage(shorten_keys)] flag

Hybrid syntax sketch

#[contractstorage]
#[contracttype]
#[derive(Clone)]
pub enum DataKey {
    #[storage(persistent, value = i128)]
    Balance(Address),
 
    #[storage(temporary, value = AllowanceValue)]
    Allowance { from: Address, spender: Address },
 
    #[storage(instance, value = Address)]
    Admin,
 
    #[storage(instance, status)]
    Initialized,
}

Generates:

pub struct DataKeyAccess<'a> { env: &'a Env }
 
impl DataKey {
    pub fn access(env: &Env) -> DataKeyAccess<'_> { ... }
}
 
impl<'a> DataKeyAccess<'a> {
    // Balance — persistent, i128
    pub fn get_balance(&self, arg0: &Address) -> i128 { ... }       // unwraps
    pub fn try_get_balance(&self, arg0: &Address) -> Option<i128> { ... }
    pub fn set_balance(&self, arg0: &Address, val: &i128) { ... }
    pub fn has_balance(&self, arg0: &Address) -> bool { ... }
    pub fn remove_balance(&self, arg0: &Address) { ... }
    pub fn update_balance(&self, arg0: &Address, f: impl FnOnce(Option<i128>) -> i128) -> i128 { ... }
    pub fn extend_ttl_balance(&self, arg0: &Address, threshold: u32, extend_to: u32) { ... }
 
    // Allowance — temporary, AllowanceValue (named fields → method params)
    pub fn try_get_allowance(&self, from: &Address, spender: &Address) -> Option<AllowanceValue> { ... }
    pub fn set_allowance(&self, from: &Address, spender: &Address, val: &AllowanceValue) { ... }
    // ...
 
    // Admin — instance, Address
    pub fn get_admin(&self) -> Address { ... }
    pub fn try_get_admin(&self) -> Option<Address> { ... }
    pub fn set_admin(&self, val: &Address) { ... }
    // ... (no per-key extend_ttl for instance)
 
    // Initialized — instance, status
    pub fn is_initialized(&self) -> bool { ... }
    pub fn set_initialized(&self) { ... }
    pub fn remove_initialized(&self) { ... }
}

6. Recommendation

Adopt Approach A (enum DataKey + #[contractstorage]) as the SDK-native solution, incorporating select elements from B and C.

Rationale:

1. Lowest migration cost. The enum DataKey pattern is already the community standard. Adding #[contractstorage] and #[storage(...)] attributes is additive — zero breaking changes, gradual adoption per call site.

2. Library, not framework. Approach A keeps the SDK composable: it doesn't take ownership of #[contracttype], doesn't force visibility constraints, doesn't bake in TTL policy. Contracts can mix typed and untyped access during migration.

3. All three safety gaps closed. Key type, value type, and storage type are all enforced at compile time. The turbofish burden is eliminated.

4. Proven concept. Both B (Axelar) and C (BlaineHeffron) validate that the community wants this. A captures the same benefits with the smallest surface area change.

5. Extensible. The hybrid elements (named fields, try_get, #[status], key compression) can be added incrementally without redesigning the core.

What NOT to adopt

• Auto-TTL on read (from B) — This is operational policy, not schema. Different contracts have different TTL strategies. Keep extend_ttl_* explicit.
• Forced private enum (from B) — Breaks cross-contract key sharing and is unnecessarily restrictive.
• Struct-based approach (C) as the primary API — Too large a departure from the existing ecosystem convention. However, soroban-sdk-tools could remain a supported community alternative for developers who prefer the struct mental model.

Minimal First Step

1. Implement #[contractstorage] proc macro in soroban-sdk-macros/src/derive_storage.rs (~300-400 lines).

   • Support #[storage(persistent|temporary|instance, value = Type)] on enum variants.
   • Generate DataKeyAccess struct with get_*, set_*, has_*, remove_*, extend_ttl_* methods.
   • Strip #[storage(...)] attributes before #[contracttype] processes the enum.

2. Add to soroban-sdk exports — re-export the macro from soroban_sdk::contractstorage.

3. Add tests — typed access tests in soroban-sdk/src/tests/, compile-fail tests for wrong-type usage.

4. Update one soroban-example (e.g., the token contract) to demonstrate the pattern.

Deferred to follow-up:

• Named fields on variants (requires transforming to tuple variants before #[contracttype])
• #[status] sugar
• try_get_* variants
• Key compression (shorten_keys)
• Optional golden-file schema tests
• Clippy-style lint warning when raw API is used alongside #[contractstorage]

---

This post is just adding another idea to the mix and isn't intended to signal that the sdk should adopt this.

[tupui]

I would love to see an official solution. Storage is super important and we should have tooling around type safety there IMO. There is also something to say around supply chain. With all the recent attacks, I am personally being even more cautious.

My hope is that it would also help debugging storage inconsistency issues. Right now errors are opaque if you store data with one type and try to use another type to get it.

You also have to manually type the output of get, which is not very convenient.

The design you propose would be similar to what we have with events which I personally like.