What problem does your feature solve?
Since Soroban Rust SDK v25, Env::default() automatically enforces Mainnet-like resource ceilings (instructions, disk read/write entries, ledger entries, and so on) on every contract test invocation, via InvocationResourceLimits::mainnet() in soroban-sdk/src/testutils/cost_estimate.rs. A contract that exceeds one of these ceilings during a test now panics with an error naming the specific resource limit that was exceeded. stellar-docs currently has no mention of this behavior anywhere in the repo (a search across the docs for InvocationResourceLimits, CostEstimate, NetworkInvocationResourceLimits, cost_estimate, disable_resource_limits, enforce_resource_limits, and related terms turns up nothing), so a developer who hits this panic for the first time has no docs-site page to consult explaining what happened or why. There is also no mention of the escape hatches the SDK provides for working around it during development, env.cost_estimate().disable_resource_limits() and env.cost_estimate().enforce_resource_limits(limits), nor any general introduction to the CostEstimate testutils API itself. The closest existing pages, docs/networks/resource-limits-fees.mdx, docs/networks/README.mdx, and docs/learn/fundamentals/fees-resource-limits-metering.mdx, cover protocol/network-level resource limits conceptually but never describe this SDK-level, test-time enforcement mechanism, and there does not appear to be any "writing tests for Soroban contracts" page under docs/build/smart-contracts/ where this would naturally fit.
This gap is more consequential as of stellar/rs-soroban-sdk#1946, "Refresh mainnet() resource limits and fees," which just merged and refreshed the hardcoded snapshot the enforcement is checked against: the instruction ceiling tightened from 600,000,000 to 400,000,000, while disk_read_entries loosened 100→200, write_entries loosened 50→200, and ledger_entries loosened 100→400. A contract using between 400M and 600M instructions that previously passed its test suite under the old ceiling may now fail with the new one, with no stellar-docs page to point affected developers to for an explanation. That PR also reworded the rustdoc comments on both InvocationResourceLimits::mainnet() and CostEstimate::fee() to stop presenting the numbers as an authoritative, permanently-accurate snapshot and instead point developers at stellar network settings --network mainnet and https://lab.stellar.org/network-limits as the live source of truth, since the hardcoded values will always eventually drift again.
The SDK itself already carries a migration guide for this behavior change, in rustdoc form, at soroban-sdk/src/_migrating/v25_resource_limits.rs (viewable on docs.rs), but stellar-docs has no equivalent page, summary, or even a link to it.
What would you like to see?
Some page under stellar-docs should explain that Env::default() enforces resource-limit ceilings on contract test invocations by default since SDK v25, what happens when a contract exceeds one (the panic and its message), and how to work around it during development using disable_resource_limits() or enforce_resource_limits() on env.cost_estimate(). It would probably also help to briefly introduce the CostEstimate testutils API in general, and to note that the specific numeric ceilings are a periodically-refreshed snapshot rather than a live value, directing readers to stellar network settings --network mainnet and https://lab.stellar.org/network-limits for current figures rather than restating numbers that will drift.
Where this content should live is left to whoever picks this up; it might fit as a new subsection of an existing testing-related page (if/when one exists under docs/build/smart-contracts/), or somewhere else that better matches stellar-docs' current structure. This issue is meant to flag the gap rather than prescribe the exact location or wording.
What alternatives are there?
The only existing source of truth for this behavior today is the SDK's own rustdoc, at soroban-sdk/src/testutils/cost_estimate.rs and the migration guide at soroban-sdk/src/_migrating/v25_resource_limits.rs (both viewable via docs.rs). Developers who don't already know to look there, or don't read release notes/CHANGELOGs closely, have no way to discover this behavior from stellar-docs before hitting the panic themselves.
Related: stellar/rs-soroban-sdk#1946 (the PR that refreshed the enforced thresholds and prompted this issue).
What problem does your feature solve?
Since Soroban Rust SDK v25,
Env::default()automatically enforces Mainnet-like resource ceilings (instructions, disk read/write entries, ledger entries, and so on) on every contract test invocation, viaInvocationResourceLimits::mainnet()insoroban-sdk/src/testutils/cost_estimate.rs. A contract that exceeds one of these ceilings during a test now panics with an error naming the specific resource limit that was exceeded. stellar-docs currently has no mention of this behavior anywhere in the repo (a search across the docs forInvocationResourceLimits,CostEstimate,NetworkInvocationResourceLimits,cost_estimate,disable_resource_limits,enforce_resource_limits, and related terms turns up nothing), so a developer who hits this panic for the first time has no docs-site page to consult explaining what happened or why. There is also no mention of the escape hatches the SDK provides for working around it during development,env.cost_estimate().disable_resource_limits()andenv.cost_estimate().enforce_resource_limits(limits), nor any general introduction to theCostEstimatetestutils API itself. The closest existing pages,docs/networks/resource-limits-fees.mdx,docs/networks/README.mdx, anddocs/learn/fundamentals/fees-resource-limits-metering.mdx, cover protocol/network-level resource limits conceptually but never describe this SDK-level, test-time enforcement mechanism, and there does not appear to be any "writing tests for Soroban contracts" page underdocs/build/smart-contracts/where this would naturally fit.This gap is more consequential as of stellar/rs-soroban-sdk#1946, "Refresh mainnet() resource limits and fees," which just merged and refreshed the hardcoded snapshot the enforcement is checked against: the instruction ceiling tightened from 600,000,000 to 400,000,000, while disk_read_entries loosened 100→200, write_entries loosened 50→200, and ledger_entries loosened 100→400. A contract using between 400M and 600M instructions that previously passed its test suite under the old ceiling may now fail with the new one, with no stellar-docs page to point affected developers to for an explanation. That PR also reworded the rustdoc comments on both
InvocationResourceLimits::mainnet()andCostEstimate::fee()to stop presenting the numbers as an authoritative, permanently-accurate snapshot and instead point developers atstellar network settings --network mainnetand https://lab.stellar.org/network-limits as the live source of truth, since the hardcoded values will always eventually drift again.The SDK itself already carries a migration guide for this behavior change, in rustdoc form, at
soroban-sdk/src/_migrating/v25_resource_limits.rs(viewable on docs.rs), but stellar-docs has no equivalent page, summary, or even a link to it.What would you like to see?
Some page under stellar-docs should explain that
Env::default()enforces resource-limit ceilings on contract test invocations by default since SDK v25, what happens when a contract exceeds one (the panic and its message), and how to work around it during development usingdisable_resource_limits()orenforce_resource_limits()onenv.cost_estimate(). It would probably also help to briefly introduce theCostEstimatetestutils API in general, and to note that the specific numeric ceilings are a periodically-refreshed snapshot rather than a live value, directing readers tostellar network settings --network mainnetand https://lab.stellar.org/network-limits for current figures rather than restating numbers that will drift.Where this content should live is left to whoever picks this up; it might fit as a new subsection of an existing testing-related page (if/when one exists under
docs/build/smart-contracts/), or somewhere else that better matches stellar-docs' current structure. This issue is meant to flag the gap rather than prescribe the exact location or wording.What alternatives are there?
The only existing source of truth for this behavior today is the SDK's own rustdoc, at
soroban-sdk/src/testutils/cost_estimate.rsand the migration guide atsoroban-sdk/src/_migrating/v25_resource_limits.rs(both viewable via docs.rs). Developers who don't already know to look there, or don't read release notes/CHANGELOGs closely, have no way to discover this behavior from stellar-docs before hitting the panic themselves.Related: stellar/rs-soroban-sdk#1946 (the PR that refreshed the enforced thresholds and prompted this issue).