feat(xdr): support CAP-83 empty tx set values and CAP-85 external executables

[Ryang-21]

What

Builds on #1576, which regenerated the XDR classes with CAP-83 and CAP-85 ungated. That PR only did the minimum to keep tsc green; this one teaches the hand-written layers what the new variants mean, and adds round-trip coverage.

Reading a tag. scValToNative now handles scvExecutableTag, decoding the SCString payload via asStringOrBytes() — the same treatment scvString and scvSymbol get, so a tag holding non-UTF-8 bytes comes back as a Uint8Array rather than a string full of U+FFFD replacement characters. Previously the variant fell through to default and leaked the raw XdrString wrapper.

Rendering a creation. buildInvocationTree renders external-executable creations instead of throwing "unknown creation type". CreateInvocation.type gains an "external" case whose details live in a new external field, typed by the new ExternalRefCreateDetails: owner, tag, address, salt, and constructorArgs for CREATE_CONTRACT_V2. The executable/preimage validation is restructured: an external ref derives its contract ID from deployer address plus salt, exactly as Wasm does, so it belongs with Wasm on the address side of that check rather than tripping it.

Resolving a reference. A contract created from an external reference carries no code hash of its own. Per CAP-85 the owner contract holds a persistent contract data entry keyed by the tag whose value is a 32-byte Wasm hash, and the host resolves the reference by reading that entry — it does not invoke the owner. New rpc.Server.getExternalRefWasmHash(ref) performs that lookup, and contract.Client.from and rpc.Server.getContractWasmByContractId use it, so both work on these contracts: resolve the reference to a hash, then load the spec or code as for any Wasm contract. getContractMethods and queryContract follow, since they build on those two.

Generating bindings. src/bindings/wasm_fetcher.ts had its own instance-to-code path that rejected every non-Wasm executable, so BindingGenerator.fromContractId and the CLI behind it failed on these contracts even once the methods above worked. It now resolves an external reference through the same getExternalRefWasmHash before fetching code, restating the server's { code, message } rejection as a WasmFetchError to match the rest of that module. The SAC branch is untouched.

CAP-83 (empty transaction set values). No behavior change is needed — StellarValueExt's new stellarValueEmptyTxSet arm and the StellarValueProposedValue struct are consumed generically. This PR covers them with tests instead.

Build fix. make xdr-json piped curl into tar. sh has no pipefail and tar can exit 0 on an empty stream, so a failed or truncated schema download passed silently. It now downloads to a file, then extracts.

Why

A tag is half of what identifies the code being deployed, so it cannot be decoded leniently: two distinct binary tags would render identically, and the rendered tree is what a signer reads before approving. Hence string | Uint8Array everywhere a tag surfaces.

Rejecting external refs in Client.from would have been a needless dead end. The reference is resolvable with lookups the SDK already has, so a client for one of these contracts costs one extra getLedgerEntries call, not a manual spec. The binding fetcher gets the same treatment for the same reason, and because a contract that Client.from can talk to but fromContractId cannot generate bindings for is a confusing split.

Coverage

• test/unit/xdr/protocol_cap83_cap85.test.ts round-trips each new type and union arm through XDR bytes and SEP-0051 JSON, and asserts the pre-existing arms of the widened unions still decode as before. These need hand-written coverage because schema_exhaustive.test.ts validates against a pinned legacy SDK build as its on-wire oracle, and that build predates both CAPs — it silently skips types the legacy SDK does not expose.
• test/unit/base/scval.test.ts covers the scvExecutableTag conversion in both its string and raw-bytes forms.
• test/unit/base/invocation.test.ts covers external-ref creation trees for V1 and V2, a binary tag, and the mismatch error. Owners in these fixtures are contracts, since only a contract can hold the tag entry.
• test/unit/server/soroban/get_contract_wasm.test.ts covers the three-hop resolution (instance → owner's tag entry → contract code), that a binary tag keys the lookup undecoded, a tag entry not holding a 32-byte hash, and a non-contract owner.
• test/unit/contract/client_from.test.ts covers Client.from on an external-reference contract end to end, and that a non-contract owner rejects before the second lookup.
• test/unit/bindings/wasm_fetcher.test.ts is new — the module had no tests. It covers the Wasm and SAC paths plus the three external-reference cases: resolution, a binary tag keying the lookup undecoded, and a non-contract owner.

[Copilot]

Pull request overview

Adds CAP-83/CAP-85 handling across XDR conversion, invocation parsing, RPC Wasm resolution, and contract clients.

Changes:

• Resolves CAP-85 external executable references and decodes executable tags.
• Adds CAP-83/CAP-85 round-trip and behavior tests.
• Updates generated references, changelog, and XDR download reliability.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/base/scval.ts	Converts executable tags to native values.
src/base/invocation.ts	Represents external-reference contract creation.
src/rpc/server.ts	Resolves references and retrieves their Wasm.
src/contract/client.ts	Builds clients from referenced Wasm.
test/unit/base/scval.test.ts	Tests executable-tag conversion.
test/unit/base/invocation.test.ts	Tests external creation parsing.
test/unit/server/soroban/get_contract_wasm.test.ts	Tests external-reference resolution.
test/unit/xdr/protocol_cap83_cap85.test.ts	Tests new XDR variants.
Makefile	Makes XDR archive downloads safer.
docs/reference/network-rpc.md	Updates generated RPC reference.
docs/reference/core-soroban-primitives.md	Updates generated invocation reference.
docs/reference/contracts-client.md	Updates generated client reference.
CHANGELOG.md	Records CAP-83/CAP-85 support.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (7)

src/base/invocation.ts:210

• This branch accepts an account-valued executableOwner, but CAP-85 resolves the tag from the owner contract's persistent storage; getExternalRefWasmHash below rejects account owners for the same reason. As written, the invocation tree renders protocol-invalid creations instead of raising the existing invalid-creation error. Require scAddressTypeContract before constructing the external details.

      } else if (
        exec.type === "contractExecutableExternalRef" &&
        preimage.type === "contractIdPreimageFromAddress"

src/base/invocation.ts:23

• CAP-85 requires the executable owner to be a contract, since the referenced tag is a contract-data entry; account addresses cannot own that entry. The public API documentation currently claims account owners are valid and conflicts with getExternalRefWasmHash, which rejects them.

 * - `owner` is the strkey of the account or contract that owns the external
 *   executable being referenced

test/unit/base/invocation.test.ts:391

• This binary-tag fixture also uses an account as the executable owner, so the invocation is invalid independently of the tag bytes. Use a contract address so the test isolates and verifies binary-tag rendering on a valid CAP-85 creation.

    const owner = randomKey();

src/contract/client.ts:275

• There is no external-reference case in test/unit/contract/client_from.test.ts; it still covers only direct Wasm and SAC instances, despite the PR's coverage statement. Add the described end-to-end success case and non-contract-owner rejection so this new multi-lookup path is exercised.

    const wasmHash =
      executable.type === "contractExecutableExternalRef"
        ? await server.getExternalRefWasmHash(executable.externalRef)
        : executable.wasmHash.value;

test/unit/xdr/protocol_cap83_cap85.test.ts:69

• This new union arm is only round-tripped through XDR bytes, although the file header and PR coverage claim SEP-0051 JSON coverage for each new arm. Add a ScVal.fromJson(scv.toJson()) assertion here; otherwise the executable-tag JSON path remains untested.

    const decoded = ScVal.fromXdr(scv.toXdr());
    expect(decoded.type).toBe("scvExecutableTag");
    expect(decoded.toXdr()).toEqual(scv.toXdr());

src/rpc/server.ts:652

• The PR description says binding generation was wired through this resolver, but src/bindings/wasm_fetcher.ts:114-115 still rejects every non-Wasm executable and test/unit/bindings/wasm_fetcher.test.ts is absent. Consequently BindingGenerator.fromContractId and its CLI still fail for external-reference contracts. Please update the fetcher to resolve this arm through the new helper and add the stated tests.

  public async getExternalRefWasmHash(
    ref: ContractExecutableExternalRef,
  ): Promise<Uint8Array> {

test/unit/base/invocation.test.ts:320

• This fixture uses a G-address as the executable owner, but CAP-85 requires a contract owner because the tag is read from contract storage. It therefore locks in rendering an invocation that the host cannot execute; use a C-address fixture instead.

This issue also appears on line 391 of the same file.

    const owner = randomKey();

[quietbits]

What happens if type is not "external" and external prop is set?

[Ryang-21]

This should not be possible given that this is mean't to be used by buildInvocationTree which takes an xdr SorobanAuthorizedInvocation. Ideally this type would be a discriminated union so that its not possible