Skip to content

Adopt spec entry ids and id-based reference resolution - #2677

Closed
leighmcculloch wants to merge 5 commits into
mainfrom
adopt-udt-type-ids
Closed

Adopt spec entry ids and id-based reference resolution#2677
leighmcculloch wants to merge 5 commits into
mainfrom
adopt-udt-type-ids

Conversation

@leighmcculloch

@leighmcculloch leighmcculloch commented Aug 10, 2026

Copy link
Copy Markdown
Member

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 borrowed Ref variants of generated types rs-stellar-xdr#560
  2. Add const XDR serialization on View types rs-stellar-xdr#562
  3. Encode contract spec XDR at const evaluation time rs-soroban-sdk#1965

A second group of PRs deliver ids on contract spec entries and in spec references. Every entry carries an 8-byte id hashed from the fully qualified name of the item it describes, and a reference to a user-defined type carries the id of the entry it refers to, so references stay unambiguous even when items share a name. This resolves the type identity problem (stellar/rs-soroban-sdk#1570) and type alias limitations (stellar/rs-soroban-sdk#1857):

  1. Add ids to contract spec entries stellar-xdr#313
  2. Regenerate with ids on contract spec entries rs-stellar-xdr#568
  3. Add ids to contract spec entries rs-soroban-sdk#1998
  4. Adopt spec entry ids and id-based reference resolution #2677 ← this PR

What

Patch stellar-xdr to stellar/rs-stellar-xdr#568 and the soroban spec crates to stellar/rs-soroban-sdk#1998, moving the workspace to stellar-xdr 28 and soroban-env-host 28.0.1, and adapt the CLI to specs whose entries carry ids:

  • soroban-spec-tools' Spec normalizes v2 entries on construction — each entry's v0 body is stored so all consumers keep matching one shape — and keeps each entry's id keyed to its body. A ScSpecTypeUdtv2 reference resolves through find_udt_v2: the entry whose id matches when one does, exactly even when entries share a name, falling back to the referenced name for specs of v0 entries.
  • Spec verification and TypeScript bindings treat a v2 entry as its body plus an identity.
  • The CLI handles the new ScVal::ExecutableTag and ContractExecutable::ExternalRef variants.

Why

Contract spec entries now carry an id hashed from the fully qualified name of the item they describe, and references to user-defined types carry the id of the entry they refer to. The CLI has to read, print, and generate bindings from specs produced by SDKs that emit them — and with ids it can resolve a reference to exactly the entry it was written against.

Known limitations

Merging depends on the upstream PRs landing and releasing, with the [patch.crates-io] git revisions replaced by published versions. Network-backed test suites need a quickstart image running a protocol 28 host.

@github-project-automation github-project-automation Bot moved this to Backlog (Not Ready) in DevX Aug 10, 2026
@leighmcculloch leighmcculloch changed the title Patch xdr and spec crates for udt type ids Adopt spec entry ids and id-based reference resolution Aug 10, 2026
@github-project-automation github-project-automation Bot moved this from Backlog (Not Ready) to Done in DevX Aug 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant