Shake specs by reachability and markers

[leighmcculloch]

Note

Part of a stack of PRs that must merge in this order.

A first group of PRs deliver const-encoded contract specs, so that contract specs are produced at compile time instead of at proc-macro execution time. This provides the foundation for the capability to construct the specs from information that is not known at proc-macro execution and only known at compile time, like the fully qualified name of a type:

1. Add const XDR serialization rs-stellar-xdr#580
2. Encode contract spec XDR at compile time #1965

A second group of PRs deliver fully qualified type names in contract specs. Instead of a type having the name Context it will have the name soroban_sdk::auth::Context. Qualified type names make it possible to uniquely identify types in the spec, even when they have the same name. This resolves several problems with contract specs the type identify problem (#1570), type aliases limitations (#1857 #1063), and optimise spec shaking data section size (#1978):

1. Widen contract spec type and event name limits stellar-xdr#312
2. Widen contract spec type and event name limits rs-stellar-xdr#566
3. Qualify type and event names #1970
4. Update stellar-xdr to 28.0.0 rs-stellar-rpc-client#108
5. Reduce qualified type and event names stellar-cli#2674

A third group of PRs use those qualified names to shake specs by reachability, so that the markers a contract carries shrink to the few entries a spec never names:

1. Shake specs by reachability and markers #2043 ← this PR
2. Shake by the recorded version stellar-cli#2720

What

Stop emitting a spec shaking marker for every user-defined type, and keep spec entries by following the references between them instead, leaving markers only on the events a contract publishes and the errors it panics with.

Why

A marker per type stood in for a reference graph the spec could not express while a type was named by a bare name, and now that a qualified name identifies exactly one definition, reachability answers which entries are used more precisely than a marker did, since it also drops a type that is marked but that nothing names. The test contract covering shaking end to end shows what that costs a contract today: the entries surviving the shake are unchanged while its markers fall from 49 to 8, its 6 published events and the 2 errors it only ever panics with.

Negotiating the rules with the build system

Two separate questions have to be answered, and they are answered in two different places.

Can this build system apply the rules this contract needs? That is a build-time question, so the env var answers it, and this change moves it to SOROBAN_SDK_BUILD_SYSTEM_SUPPORTS_SPEC_SHAKING_V3. It cannot keep the v2 name: a build system announcing v2 shakes by markers alone, and on a v3 contract, where types deliberately carry no marker, that strips every type instead of keeping the used ones. Trusting a v2 announcement would ship a spec that is wrong, not merely unshaken, so the SDK refuses to build and asks for a stellar-cli carrying stellar/stellar-cli#2720.

Which rules is a given contract shaken by? That is a read-time question about a wasm that may have been built long ago, so the contract answers it itself, with the rssdk_spec_shaking meta entry it records — moved here from 2 to 3. soroban_spec::shaking::filter takes that version and applies the matching rules: V2 keeps an entry only if it carries a marker, V3 also follows the references from functions, events, and types, and a contract recording no version at all is left unshaken. A build system therefore announces every rule set it can apply and lets each contract select among them.

SemVer Change

• Major (vX._._) - Breaking change to the public API.
• Minor (v_.Y._) - Additive change to the public API.
• Patch (v_._.Z) - No change to the public API.