Discuss harmful / easy mistakes that don't scale or could result in stuck contracts

Start with the storage documentation at developers.stellar.org/docs/learn/encyclopedia/storage/persisting-data and compare its guidance with the Soroban examples pull request #369. Review the issue's concerns about ledger-entry size, fees, and congestion, then determine how a do-not-do page should explain bounded versus unbounded collections. Done means the relevant documentation is updated with clear guidance and examples or links for safer storage patterns.

I think we need to discuss some of the harmful or easy mistakes to make with contract data, that can result in a contract not scaling, or getting stuck when data grows past a certain size.

The main case that's come up recently is seeing folks try to use the built in container types soroban_sdk::{Vec, Map} to hold what could be unbounded collections and storing those collections in a single contract data entry.

The docs on storage, such as the page below, don't discuss how collections stored in contract data ledger entries

• https://developers.stellar.org/docs/learn/encyclopedia/storage/persisting-data

Problems arise when contract callers can cause collections to grow. Contract data ledger entries are limited in size by the max size for any ledger entry. This means there's a point where writing new data to a collection will result in an error, because it won't be able to be written back out. Even before that limit is reached the fees related to building and writing the collection at that size may be impractical in terms of other resource costs.

Separate to size constraints the use of collections in a single entry, where multiple users may write to, will cause congestion since all transactions writing to the shared collection would need to occur serially. This will make using the contract more expensive since it won't be able to utilise multiple execution lanes. Simulation is likely to fail to estimate the cost of doing so if it is being written to by multiple users inside a single ledger.

Collections that are inherently unbounded in size should instead be stored with each individual entry in the collection being a separate contract data ledger entry. There's an unmerged example for how to do that here:

• https://github.com/stellar/soroban-examples/pull/369

This topic would also be a good candidate for a "do-not-do" style page, such as like the on that Postgres has in its wiki:

• https://wiki.postgresql.org/wiki/Don%27t_Do_This