Embed markers for used types/events to enable spec filtering #1672

leighmcculloch · 2026-01-09T12:40:47Z

What

Embed markers in the WASM data section for each type/event that is used at external boundaries. These markers enable post-build tools to filter unused entries from the contractspecv0 section.

Changes:

Add spec_marker module with marker generation logic
Update all derive macros (derive_struct, derive_struct_tuple, derive_enum, derive_enum_int, derive_error_enum_int, derive_event) to embed markers
Markers are placed inside __include_spec_marker() functions with volatile reads
Markers survive dead code elimination (DCE) only if the type/event is actually used

Why

Contract WASM files can contain unused type and event definitions in the contractspecv0 custom section that inflate binary size unnecessarily.

The problem: Any exported contracttypes or contractevents defined in the SDK or any library that don't get used in the importing contract still end up in the contract spec. This results in awkward behaviour where we avoid exporting contracttypes in the SDK, even though doing so would be convenient.

Why the SDK can't fix this alone: Because of how proc-macros run in isolation and cannot coordinate in WASM builds in Rust, there's nothing the soroban-sdk can do to identify whether a contracttype that sometimes needs to be exported hasn't been used and can be excluded.

Solution: The SDK embeds markers in the regular data section for each type/event when it's used. These markers survive DCE only if the corresponding code is reachable. A post-build tool (stellar-cli) extracts these markers and filters the spec accordingly.

Close #1569
Close stellar/stellar-cli#2030

Side-effects

A side-effect of this change, is that types/events brought into a contract from a contractimport can now be automatically exported from that contract if they use the types at their boundary. This is why the change also removes the export = false from types/events that come from a contractimport.

Close #1330

How

The SDK embeds markers using volatile reads in conversion/publish functions:

Marker format (12 bytes):

Bytes 0-3: SpEc magic prefix (alternating case to avoid false positives)
Bytes 4-11: 64-bit truncated SHA256 hash of the spec entry XDR bytes

Embedding mechanism:

impl MyType {
    #[inline(always)]
    fn __include_spec_marker() {
        #[cfg(target_family = "wasm")]
        {
            static MARKER: [u8; 12] = *b"SpEc\x93\xd5\x05\x04\x36\x68\x40\xd2";
            let _ = unsafe { ::core::ptr::read_volatile(MARKER.as_ptr()) };
        }
    }
}

When markers are included:

Types: __include_spec_marker() is called from TryFromVal implementations via IncludeSpec trait
Events: __include_spec_marker() is called from the publish() method

Why this works: If a type/event is never used at an external boundary, its __include_spec_marker() function is never called, and DCE removes both the function and its marker. If the type is used, the marker survives in the data section.

CLI Support Required

This feature requires CLI support for filtering specs using these markers. See: stellar/stellar-cli#2353

Try It Out

Install the modified stellar-cli that strips unused specs:

cargo install --locked --git https://github.com/stellar/stellar-cli --branch spec-clean stellar-cli

Import the modified soroban-sdk that marks used specs:

[dependencies]
soroban-sdk = { git = "https://github.com/stellar/rs-soroban-sdk", branch = "spec-markers" }

[dev-dependencies]
soroban-sdk = { git = "https://github.com/stellar/rs-soroban-sdk", branch = "spec-markers", features = ["testutils"] }"

Build using the stellar-cli:

stellar contract build

Inspect the contract interface and it should only show types actually used at the boundary of the contract (inputs, outputs, and events):

stellar contract info interface --wasm target/wasm32v1-none/release/contract.wasm

Todo

Figure out a roll out plan, because you can't really use this sdk until you use the new cli, otherwise your specs will increase in size rather than decrease because imported types are now exported then stripped.
Evaluate the cost of the volatile read on a large contract (expect impact is small)
Look for alternative ways other than a volatile read to force the marker to stick around
- Try black box
- Try #[used]
Markers need to be included for any nested user defined types and types inside containers

mootz12

Looks good overall. Leaving review as comment for now as I haven't looked at the CLI side or done much testing.

One thing to note is this might have some impacts if the spec-marker ever changes to release complexity between the CLI and SDK.

Might not be anything we can do about it :/

mootz12 · 2026-01-13T18:35:25Z

soroban-sdk-macros/src/spec_marker.rs

+/// 2. Extract the hash from each marker
+/// 3. Match against specs in contractspecv0 section (by hashing each spec)
+/// 4. Strip unused specs from contractspecv0
+// TODO: Move the spec marker logic into a crate that can be shared with the CLI.


Is this needed yet?

soroban-spec/src/marker.rs

mootz12 · 2026-01-13T18:40:46Z

soroban-sdk-macros/src/spec_marker.rs

+    use super::*;
+
+    #[test]
+    fn test_spec_marker() {


(picky) can we add a test here to assert against a fixed spec_marker? It should fail if the structure of spec_market changes, whereas this one won't as long as the first 4 bytes and len don't change.

mootz12 · 2026-01-13T18:51:09Z

soroban-spec/src/marker.rs

+/// Spec marker generation for identifying used spec entries.
+///
+/// The marker is a byte array in the data section with a distinctive pattern:
+/// - 4 bytes: "SpEc" prefix


is it worthwhile to version tag this at all?

SpEcV1

In the event this ever changes, would we need to maintain backwards compatibility? Or is it more of a "use the correct CLI version for your given SDK version"

We could add this. The SDK will also have the SDK version embedded inside the meta custom section and I was planning to update the stellar-cli, so I think it can work out from that version what it should do.

soroban-sdk-macros/src/derive_event.rs

mootz12 · 2026-01-13T19:01:17Z

soroban-sdk-macros/src/derive_struct_tuple.rs

+        // Create a marker that identifies this spec entry. The marker is a byte array
+        // in the data section with a distinctive pattern: "SpEc" + truncated SHA256.
+        // Post-build tools can scan the data section for "SpEc" markers and match
+        // against specs in contractspecv0.
+        let marker = spec_marker::spec_marker(spec_xdr);
+        let marker_lit = proc_macro2::Literal::byte_string(&marker);
+        let marker_len = marker.len();
+        Some(quote! {
+            impl #path::IncludeSpecMarker for #ident {
+                #[doc(hidden)]
+                #[inline(always)]
+                fn include_spec_marker() {
+                    // Include markers for nested field types.
+                    #(<#field_types as #path::IncludeSpecMarker>::include_spec_marker();)*
+                    #[cfg(target_family = "wasm")]
+                    {
+                        // Marker in data section. Post-build tools can scan for "SpEc"
+                        // patterns and match against specs in contractspecv0.
+                        static MARKER: [u8; #marker_len] = *#marker_lit;
+                        // Volatile read prevents DCE within live function.
+                        let _ = unsafe { ::core::ptr::read_volatile(MARKER.as_ptr()) };
+                    }
+                }
+            }
+        })


Could we extract this logic out of the derive_* files to reduce some code duplication?

soroban-sdk-macros/src/derive_struct_tuple.rs

soroban-sdk/src/into_val_for_contract_fn.rs

Co-authored-by: mootz12 <38118608+mootz12@users.noreply.github.com>

mootz12 · 2026-01-14T15:39:34Z

Is it worth considering putting this behind a build flag of some sort? This way, the CLI could provide it for users so the process is hidden.

If some1 builds directly with cargo and doesn't provide the flag, the spec markers won't be added to avoid polluting the WASM.

leighmcculloch · 2026-01-14T21:35:42Z

That's a good idea, at least during a rollout period. Something to note though is that part of this change is changing specs so they always output to the custom section, even specs from libraries and imports, so that the cli can then narrow them down to the ones being used. If you import a library today you get way more pollution than what these markers introduce. If you import with contractimport you get no type exporting which is really broken. So any world where we keep the old way is going to propogate continued broken experiences.

leighmcculloch · 2026-01-30T11:31:34Z

One thing to note is this might have some impacts if the spec-marker ever changes to release complexity between the CLI and SDK.

Might not be anything we can do about it :/

Is it worth considering putting this behind a build flag of some sort? This way, the CLI could provide it for users so the process is hidden.

If some1 builds directly with cargo and doesn't provide the flag, the spec markers won't be added to avoid polluting the WASM.

I had a look at doing this, so that the sdk worked the way it does today if not used with a new cli. The approach I tried was that the cli would set a special cfg via rustflags, that the sdk would use to control if it should use this new approach or not. But it results in much more complex macro code because there's essentially two paths for everything.

Part of the problem is that as part of this change more specs, all specs actually including those from contractimport!, will now initially end up in the wasm file. Today we selectively export specs as a best effort guess, and so some specs like those generated using contractimport! do not do not get exported. But with this change the selection of specs to keep will be done in the CLI, and we will now export all specs from imports and libraries. Todays selection logic is imperfect. If we kept that old imperfect logic, someone building with cargo build and stellar contract build would probably see missing spec entries which would look like a bug.

I think it'd be preferred if the cargo build output was at least a superset, so I don't think we should try and keep the imperfect spec selection around, and all used specs are always included, and the cli is just an optimisation step now.

So instead I've added a cfg that the cli sets to indicate it supports optimising contract specs, and the SDK can output a warning if its being built with an old CLI or no CLI.

leighmcculloch added 7 commits January 9, 2026 10:31

make contract spec lazy-loaded on type usage

c3632eb

implement lazy spec loading with markers

23993bd

replace xdr encoding with magic prefix in spec markers

1b2a428

simplify spec marker encoding to use sha256 hash

63bae73

rename __include_spec to __include_spec_marker

99ff52e

refactor spec marker generation and usage

a4d4c7b

Simplify IncludeSpecMarker trait and rename from IncludeSpec

3b7ef81

leighmcculloch force-pushed the spec-markers branch from 0c24a90 to 3b7ef81 Compare January 9, 2026 13:05

leighmcculloch added 19 commits January 9, 2026 23:12

simplify spec marker hash computation

1028afc

simplify spec marker generation and remove unused constants

437eb77

extract link_section_attr into separate variable

11ef622

rename link_section_attr to export_gen

c708308

inline spec export attribute and simplify spec_xdr call

9e1d20f

add conditional spec marker attribute for events

5b41e20

remove soroban-token-sdk dependency from empty test

1a15573

token test

09b83d0

spec test

652e56f

remove token test directory

0d5d52a

remove test_token package from lock file

bd1698e

add check_c function and import ErrorC

cb50f07

use #[used] instead of volatile read

ca04d3b

update contract wasm and spec markers

1d38b9e

replace used attribute with volatile read for markers

3e7bbc2

collect field types for spec marker inclusion

4788682

Merge main into spec-markers

3320fa3

update contract spec marker hashes

41ece64

add bn254 crypto type markers

de9e494

mootz12 reviewed Jan 13, 2026

View reviewed changes

leighmcculloch and others added 2 commits January 14, 2026 06:18

typo

dfe60be

Co-authored-by: mootz12 <38118608+mootz12@users.noreply.github.com>

deduplicate variant field types in spec marker generation

265daec

brozorec mentioned this pull request Jan 16, 2026

🎁 [Feature Request]: feature flags to reduce compiled contract size OpenZeppelin/stellar-contracts#522

Closed

leighmcculloch added 2 commits January 30, 2026 16:41

Merge branch 'main' into spec-markers

751e0a0

add warning when building wasm without spec optimization

2775493

leighmcculloch added 5 commits January 30, 2026 22:11

move spec marker to soroban-spec crate

3c57623

add SpecMarker type alias and shorten const name

e0ba97d

rename generate to generate_for_xdr and add marker functions

7e6c3db

extract spec marker impl generation to shared module

326099e

gate spec markers behind experimental_spec_resolver_v2 feature

15c0d29

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Embed markers for used types/events to enable spec filtering #1672

Embed markers for used types/events to enable spec filtering #1672

Uh oh!

leighmcculloch commented Jan 9, 2026 •

edited

Loading

Uh oh!

mootz12 left a comment

Uh oh!

mootz12 Jan 13, 2026

Uh oh!

Uh oh!

mootz12 Jan 13, 2026

Uh oh!

mootz12 Jan 13, 2026

Uh oh!

leighmcculloch Jan 13, 2026

Uh oh!

Uh oh!

mootz12 Jan 13, 2026

Uh oh!

Uh oh!

Uh oh!

mootz12 commented Jan 14, 2026

Uh oh!

leighmcculloch commented Jan 14, 2026

Uh oh!

leighmcculloch commented Jan 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Embed markers for used types/events to enable spec filtering #1672

Are you sure you want to change the base?

Embed markers for used types/events to enable spec filtering #1672

Uh oh!

Conversation

leighmcculloch commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

Side-effects

How

CLI Support Required

Try It Out

Todo

Uh oh!

mootz12 left a comment

Choose a reason for hiding this comment

Uh oh!

mootz12 Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mootz12 Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

mootz12 Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

leighmcculloch Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mootz12 Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mootz12 commented Jan 14, 2026

Uh oh!

leighmcculloch commented Jan 14, 2026

Uh oh!

leighmcculloch commented Jan 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

leighmcculloch commented Jan 9, 2026 •

edited

Loading