spec shaking v2: Consider whether storage types should be included in specs

[leighmcculloch]

What problem does your feature solve?

With the experimental_spec_shaking_v2 feature, spec entries are included or excluded based on whether the Rust compiler's dead code elimination preserves their markers. Currently, markers are only triggered at external contract boundaries: function parameters, return values, and event publishes. Types used only for storage access are intentionally excluded because storage is considered an internal implementation detail.

However, there's a question of whether storage types should also trigger marker inclusion in specs, similar to how events do. The viewpoint from some people is that storage types describe on-chain data that could be read directly by indexers or explorers outside the contract interface, and knowing the storage schema could help with debugging or off-chain tooling.

With v1 spec system the intent was that storage types would be marked as private types and would therefore be excluded. For people migrating from v2 to v1 they may have had storage types exported if they were public which is common in contracts and so it may be surprising that they are now not exported.

While not exactly the same thing, Soroban’s type system was designed to be expressive and readable and understandable by other systems, and at the very least debuggers. Specs are not required for that, but for some innovation it might be helpful.

This issue is to discuss whether the current behavior (excluding storage-only types from specs) is the right default, or whether there are compelling use cases for including them.

What would you like to see?

A decision on whether storage-only types should be included in contract specs when experimental_spec_shaking_v2 is enabled.

Some arguments to kick off discussion:

Arguments for excluding storage types (current behavior):

• Specs have always described the public callable interface of a contract
• Storage is an implementation detail — callers never interact with storage types directly
• Including storage types would bloat specs and pollute a caller's view with implementation details they don't need, the exported types may appear to make promises about structure that the developer doesn’t intended to hold true over time
• Events are included because they are observable by external consumers; storage is not analogous

Arguments for including storage types:

• Storage types describe on-chain data that could be read directly by indexers or explorers outside the contract interface
• Knowing the storage schema could help with debugging or off-chain tooling

[tupui]

Thanks for following up on that.

I am +1 on including the storage types as this is also part of the spec and makes it clear to what things are mapping to. It's an implementation detail but to me it's important to have a full information about storage and invariants. In the end this corresponds to a DB schema and as such I find it natural to be in the spec. As we get more data migration tools, I would think that could also be of help.