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

CHANGELOG.md

@@ -14,13 +14,18 @@ A breaking change will get clearly marked in this log.
 - `rpc.Server.queryContract<T>(contractId, method, args?, networkPassphrase?)`: a one-line read-only contract call that builds a client, simulates the method, and returns `{ result, isReadCall }` — the spec-decoded return value plus whether this specific call is a signature-free read that wrote no state (per-call, reflecting the given `args`). No manual transaction assembly, signing, or submission. Works for both Wasm contracts and built-in Stellar Asset Contracts (SACs) ([#1502](https://github.com/stellar/js-stellar-sdk/pull/1502)).
 - `rpc.Server.getContractMethods(contractId, networkPassphrase?)`: lists a contract's callable methods and their signatures (name, inputs, outputs, and doc string) for discovery and tooling, without invoking or simulating anything. Adds the `Api.ContractMethod` and `Api.ContractMethodInput` types ([#1502](https://github.com/stellar/js-stellar-sdk/pull/1502)).
 - `rpc.Server.getContractInstance(contractId)`: returns a contract's `xdr.ScContractInstance` (its executable and instance storage) ([#1501](https://github.com/stellar/js-stellar-sdk/pull/1501)).
+- `rpc.Server.getExternalRefWasmHash(ref)`: resolves a CAP-85 external executable reference to the 32-byte Wasm hash it names, by reading the persistent tag entry on the owner contract ([#1577](https://github.com/stellar/js-stellar-sdk/pull/1577)).
 - `contract.Client.from`, `fromWasm`, and `fromWasmHash` are now generic (`<T>`) and return `Client & T`, giving typed, autocompleted contract methods without code generation. The type parameter defaults to `unknown`, so existing untyped calls are unchanged ([#1502](https://github.com/stellar/js-stellar-sdk/pull/1502)).
 - `ClientOptions.server`: pass an existing `rpc.Server` to `contract.Client.from` to reuse its transport (headers, interceptors, `allowHttp`) instead of constructing a new one ([#1502](https://github.com/stellar/js-stellar-sdk/pull/1502)).
+- The XDR schema now covers [CAP-83](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0083.md) (empty transaction set values) and [CAP-85](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0085.md) (external contract executables), adding `xdr.StellarValueType.stellarValueEmptyTxSet` with the `xdr.StellarValueExtEmptyTxSet` arm and its `xdr.StellarValueProposedValue` struct, `xdr.ContractExecutableType.contractExecutableExternalRef` with the `xdr.ContractExecutableExternalRefArm` arm and its `xdr.ContractExecutableExternalRef` struct (an `executableOwner` address plus a `tag`), and the `xdr.ScValType.scvExecutableTag` / `xdr.ScValExecutableTag` value ([#1577](https://github.com/stellar/js-stellar-sdk/pull/1577)).
 - `Keypair.signMessage(message)` and `Keypair.verifyMessage(message, signature)`: sign and verify arbitrary messages per [SEP-53](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0053.md), for proving Stellar address ownership off-chain. The message (a UTF-8 string or `Buffer`) is prefixed with `"Stellar Signed Message:\n"`, SHA-256 hashed, and signed/verified with the keypair's ed25519 key — parity with the Python/Java SDKs and stellar-cli ([#1513](https://github.com/stellar/js-stellar-sdk/pull/1513)).
 
 ### Changed
 - `contract.Client.from` now supports built-in Stellar Asset Contracts (SACs): when the contract's executable is a SAC, the client is built from the embedded SAC spec (lazily imported so bundlers can code-split it out of the common path) instead of downloading Wasm, which a SAC has none of on-chain ([#1501](https://github.com/stellar/js-stellar-sdk/pull/1501)).
 - `rpc.Server.getContractWasmByContractId` now rejects a SAC with a structured `{ code: 400 }` error pointing to `contract.Client.from`, instead of failing while decoding a nonexistent Wasm hash; the not-found rejection is now `{ code: 404, message: "Could not obtain contract instance from server" }` ([#1501](https://github.com/stellar/js-stellar-sdk/pull/1501)).
+- `scValToNative` converts an `scvExecutableTag` to its tag: a string when the bytes are valid UTF-8, otherwise the raw bytes (same rule as `scvString` and `scvSymbol`) ([#1577](https://github.com/stellar/js-stellar-sdk/pull/1577)).
+- `buildInvocationTree` renders CAP-85 external-executable creations instead of throwing. `CreateInvocation.type` gains an `"external"` case, whose details live in a new `external` field (`owner`, `tag`, `address`, `salt`, and `constructorArgs` for `CREATE_CONTRACT_V2`). `tag` is `string | Uint8Array` — an executable tag is an unbounded `SCString`, so a binary one is returned as raw bytes rather than lossily decoded ([#1577](https://github.com/stellar/js-stellar-sdk/pull/1577)).
+- `contract.Client.from` and `rpc.Server.getContractWasmByContractId` support contracts created from a CAP-85 external executable reference. The reference names an owner contract and a tag; the owner holds a persistent contract data entry keyed by that tag whose value is the Wasm hash, so both methods resolve that entry and then load the Wasm as usual ([#1577](https://github.com/stellar/js-stellar-sdk/pull/1577)).
 - The UMD (`dist/`) build now sets `inlineDynamicImports` so the single-file bundle stays whole despite the SAC spec's lazy `import()` ([#1501](https://github.com/stellar/js-stellar-sdk/pull/1501)).
 
 ### Fixed

Makefile

@@ -72,7 +72,12 @@ xdr: xdr-json xdr-classes
 xdr-json:
 	rm -rf $(BUILD)/stage
 	mkdir -p $(BUILD)/stage/xdr
-	curl -fsSL "$(XDR_REPO)/archive/$(XDR_COMMIT).tar.gz" | tar -xz -C $(BUILD)/stage --strip-components=1
+	# Download to a file rather than piping into tar: a failed or truncated
+	# download makes curl exit non-zero, which a pipeline would hide (sh has
+	# no pipefail) since tar can still exit 0 on an empty stream.
+	curl -fsSL -o $(BUILD)/stage.tar.gz "$(XDR_REPO)/archive/$(XDR_COMMIT).tar.gz"
+	tar -xzf $(BUILD)/stage.tar.gz -C $(BUILD)/stage --strip-components=1
+	rm -f $(BUILD)/stage.tar.gz
 	@for f in $(XDR_FILES); do \
 		test -s "$(BUILD)/stage/$$f" || { echo "error: $$f missing or empty in $(XDR_COMMIT)" >&2; exit 1; }; \
 		mv "$(BUILD)/stage/$$f" "$(BUILD)/stage/xdr/$$f"; \

docs/reference/contracts-client.md

@@ -706,6 +706,11 @@ If the contract is a built-in Stellar Asset Contract (SAC), the embedded
 SAC spec is used instead of downloading Wasm, since a SAC has no Wasm
 executable on-chain.
 
+If the contract was created from a CAP-85 external executable reference,
+the reference is resolved to a Wasm hash first (see
+`rpc.Server.getExternalRefWasmHash`), then the spec is read from
+that Wasm.
+
 ```ts
 static from<T = unknown>(options: ClientOptions): Promise<Client & T>;
 ```
@@ -732,7 +737,7 @@ const client = await contract.Client.from<MyContract>(options);
 const tx = await client.increment(); // typed
 ```
 
-**Source:** [src/contract/client.ts:241](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/client.ts#L241)
+**Source:** [src/contract/client.ts:246](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/client.ts#L246)
 
 ### `Client.fromWasm(wasm, options)`
 
@@ -830,7 +835,7 @@ txFromJSON: <T>(json: string) => AssembledTransaction<T>;
 
 - **`json`** — `string` (required)
 
-**Source:** [src/contract/client.ts:292](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/client.ts#L292)
+**Source:** [src/contract/client.ts:298](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/client.ts#L298)
 
 ### `client.txFromJson(json)`
 
@@ -842,7 +847,7 @@ txFromJson<T>(json: string): AssembledTransaction<T>;
 
 - **`json`** — `string` (required)
 
-**Source:** [src/contract/client.ts:276](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/client.ts#L276)
+**Source:** [src/contract/client.ts:282](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/client.ts#L282)
 
 ### `client.txFromXDR(xdrBase64)`
 
@@ -854,7 +859,7 @@ txFromXDR<T>(xdrBase64: string): AssembledTransaction<T>;
 
 - **`xdrBase64`** — `string` (required)
 
-**Source:** [src/contract/client.ts:294](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/client.ts#L294)
+**Source:** [src/contract/client.ts:300](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/client.ts#L300)
 
 ## contract.DEFAULT_TIMEOUT
 

docs/reference/core-soroban-primitives.md

@@ -804,7 +804,7 @@ s.simulateTransaction(tx).then(
 );
 ```
 
-**Source:** [src/base/invocation.ts:125](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L125)
+**Source:** [src/base/invocation.ts:151](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L151)
 
 ## buildWithDelegatesEntry
 
@@ -1042,7 +1042,7 @@ scvSortedMap(items: ScMapEntry[]): ScVal
 
 - **`items`** — `ScMapEntry[]` (required) — the unsorted map entries
 
-**Source:** [src/base/scval.ts:476](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/scval.ts#L476)
+**Source:** [src/base/scval.ts:477](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/scval.ts#L477)
 
 ## walkInvocationTree
 
@@ -1061,7 +1061,7 @@ walkInvocationTree(root: SorobanAuthorizedInvocation, callback: InvocationWalker
 - **`root`** — `SorobanAuthorizedInvocation` (required) — the tree to explore
 - **`callback`** — `InvocationWalker` (required) — the callback to execute for each node
 
-**Source:** [src/base/invocation.ts:222](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L222)
+**Source:** [src/base/invocation.ts:258](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L258)
 
 ## Types
 
@@ -1211,45 +1211,57 @@ validUntilLedgerSeq: number;
 
 Details about a contract creation invocation.
 
-- `type` indicates if this creation was a custom contract (`'wasm'`) or a
-  wrapping of an existing Stellar asset (`'sac'`)
+- `type` indicates if this creation was a custom contract (`'wasm'`), a
+  wrapping of an existing Stellar asset (`'sac'`), or a reference to an
+  external executable (`'external'`, see CAP-85)
 - `asset` is set when `type=='sac'`, containing the canonical `Asset`
   being wrapped by this Stellar Asset Contract
 - `wasm` is set when `type=='wasm'`, containing additional creation parameters
+- `external` is set when `type=='external'`, containing the referenced
+  executable and the creation parameters
 
 ```ts
 interface CreateInvocation {
   asset?: string;
-  type: "wasm" | "sac";
+  external?: ExternalRefCreateDetails;
+  type: "wasm" | "sac" | "external";
   wasm?: WasmCreateDetails;
 }
 ```
 
-**Source:** [src/base/invocation.ts:28](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L28)
+**Source:** [src/base/invocation.ts:53](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L53)
 
 #### `createInvocation.asset`
 
 ```ts
 asset?: string;
 ```
 
-**Source:** [src/base/invocation.ts:30](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L30)
+**Source:** [src/base/invocation.ts:55](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L55)
+
+#### `createInvocation.external`
+
+```ts
+external?: ExternalRefCreateDetails;
+```
+
+**Source:** [src/base/invocation.ts:57](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L57)
 
 #### `createInvocation.type`
 
 ```ts
-type: "wasm" | "sac";
+type: "wasm" | "sac" | "external";
 ```
 
-**Source:** [src/base/invocation.ts:29](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L29)
+**Source:** [src/base/invocation.ts:54](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L54)
 
 #### `createInvocation.wasm`
 
 ```ts
 wasm?: WasmCreateDetails;
 ```
 
-**Source:** [src/base/invocation.ts:31](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L31)
+**Source:** [src/base/invocation.ts:56](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L56)
 
 ### DelegateSignature
 
@@ -1316,31 +1328,97 @@ interface ExecuteInvocation {
 }
 ```
 
-**Source:** [src/base/invocation.ts:42](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L42)
+**Source:** [src/base/invocation.ts:68](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L68)
 
 #### `executeInvocation.args`
 
 ```ts
 args: any[];
 ```
 
-**Source:** [src/base/invocation.ts:46](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L46)
+**Source:** [src/base/invocation.ts:72](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L72)
 
 #### `executeInvocation.function`
 
 ```ts
 function: string;
 ```
 
-**Source:** [src/base/invocation.ts:44](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L44)
+**Source:** [src/base/invocation.ts:70](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L70)
 
 #### `executeInvocation.source`
 
 ```ts
 source: string;
 ```
 
-**Source:** [src/base/invocation.ts:43](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L43)
+**Source:** [src/base/invocation.ts:69](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L69)
+
+### ExternalRefCreateDetails
+
+Details about a contract creation from an external executable (CAP-85).
+
+- `owner` is the strkey of the account or contract that owns the external
+  executable being referenced
+- `tag` is the owner-scoped name of that executable. It is an unbounded
+  `SCString`, so it is not always text: a lenient UTF-8 decode would render
+  two distinct tags identically, and the tag is half of what identifies the
+  code being deployed. Binary tags come back as raw bytes, matching
+  `scValToNative`
+- `address` is the strkey of the deployer and `salt` its hex-encoded salt,
+  which together derive the new contract's ID
+
+```ts
+interface ExternalRefCreateDetails {
+  address: string;
+  constructorArgs?: any[];
+  owner: string;
+  salt: string;
+  tag: string | Uint8Array<ArrayBufferLike>;
+}
+```
+
+**Source:** [src/base/invocation.ts:32](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L32)
+
+#### `externalRefCreateDetails.address`
+
+```ts
+address: string;
+```
+
+**Source:** [src/base/invocation.ts:35](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L35)
+
+#### `externalRefCreateDetails.constructorArgs`
+
+```ts
+constructorArgs?: any[];
+```
+
+**Source:** [src/base/invocation.ts:38](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L38)
+
+#### `externalRefCreateDetails.owner`
+
+```ts
+owner: string;
+```
+
+**Source:** [src/base/invocation.ts:33](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L33)
+
+#### `externalRefCreateDetails.salt`
+
+```ts
+salt: string;
+```
+
+**Source:** [src/base/invocation.ts:36](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L36)
+
+#### `externalRefCreateDetails.tag`
+
+```ts
+tag: string | Uint8Array<ArrayBufferLike>;
+```
+
+**Source:** [src/base/invocation.ts:34](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L34)
 
 ### IntLike
 
@@ -1368,31 +1446,31 @@ interface InvocationTree {
 }
 ```
 
-**Source:** [src/base/invocation.ts:58](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L58)
+**Source:** [src/base/invocation.ts:84](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L84)
 
 #### `invocationTree.args`
 
 ```ts
 args: CreateInvocation | ExecuteInvocation;
 ```
 
-**Source:** [src/base/invocation.ts:60](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L60)
+**Source:** [src/base/invocation.ts:86](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L86)
 
 #### `invocationTree.invocations`
 
 ```ts
 invocations: InvocationTree[];
 ```
 
-**Source:** [src/base/invocation.ts:61](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L61)
+**Source:** [src/base/invocation.ts:87](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L87)
 
 #### `invocationTree.type`
 
 ```ts
 type: "create" | "execute";
 ```
 
-**Source:** [src/base/invocation.ts:59](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L59)
+**Source:** [src/base/invocation.ts:85](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L85)
 
 ### InvocationWalker
 
@@ -1405,7 +1483,7 @@ other return values are ignored.
 type InvocationWalker = (node: SorobanAuthorizedInvocation, depth: number, parent?: SorobanAuthorizedInvocation) => boolean | null | void
 ```
 
-**Source:** [src/base/invocation.ts:76](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L76)
+**Source:** [src/base/invocation.ts:102](https://github.com/stellar/js-stellar-sdk/blob/main/src/base/invocation.ts#L102)
 
 ### NativeToScValOpts