v17.3.0

v17.3.0: Protocol 30

Added

• CAP-84 muxed contract (W…) addresses. StrKey adds encodeMuxedContract(), decodeMuxedContract() and isValidMuxedContract(). Address adds the muxedContract type and Address.muxedContract(). The new encodeMuxedContractAddress() builds a W… address from a C… address and an ID. extractBaseAddress() also accepts a C… address, which it returns unchanged, and a W… address, for which it returns the base C… address. TransactionBuilder.addSacTransferOperation() accepts a W… destination (#1811).
• Horizon contract_credited effects (ContractCredited) have optional contract_muxed and contract_muxed_id fields. Horizon sets them when a Stellar Asset Contract transfer or mint sends to a muxed contract (W…) address. contract_muxed_id is a decimal string (#1836, stellar-horizon#237).
• The XDR types are regenerated from stellar-xdr with CAP-84, CAP-87 and CAP-88 enabled. xdr.ScAddress adds the scAddressTypeMuxedContract arm and xdr.MuxedContract. xdr.ContractCostType adds the ML-DSA cost types, from mlDsa44DecodeVerifyingKey to verifyMlDsa87Sig. xdr.StellarValueType adds stellarValueSignedMs and stellarValueEmptyTxSetMs, with xdr.StellarValueSignedMsValue and xdr.StellarValueProposedMsValue. The new SC_SPEC_TYPE_NAME_LIMIT constant (1024) raises the limit on contract spec type names from 60. Code that switches over these unions with an exhaustive check must handle the new arms (#1795, #1796, #1797).

Changed

• inSuccessfulContractCall on rpc.Api.EventResponse and rpc.Api.RawEventResponse is optional and deprecated, because newer RPC servers no longer return it from getEvents (#1836, stellar-rpc#1050). With such a server it is undefined. Code that uses it as a boolean can fail to compile under strict. The field will be removed in the next major release.
• The rpc.Server constructor throws when timeout is not 0 or a whole number of milliseconds up to 2147483647. Examples are NaN, a negative number or a fraction. Before, it accepted any value and ignored it. The CLI's --timeout flag has the same upper limit (#1802).
• StellarToml.Resolver.resolve() rejects before the request when allowedRedirects is not 0 or a whole number up to Number.MAX_SAFE_INTEGER. Before, it passed the value to the HTTP client. In Node, the Fetch build followed redirects without limit for NaN, and both builds did so for Infinity (#1809).
• TransactionBuilder.setTimeout() now throws "timeout ends before min_time" when a positive timeout ends before an existing minTime. Before, it built a transaction with minTime after maxTime, which is never valid (#1781).
• When you set maxRedirects or maxContentLength, the Fetch client rejects a successful response whose body is not valid UTF-8, with "Response body is not valid UTF-8". Before, it replaced the invalid bytes with U+FFFD and returned the result. The client still ignores the charset of Content-Type, because a stellar.toml file and a federation response must be UTF-8. A non-2xx response still rejects with its HTTP error (#1804).
• Federation.Server.createForDomain() and Federation.Server.resolve() reject a FEDERATION_SERVER URL from stellar.toml that has a user name or password, or a scheme other than http: or https:, even when allowHttp is set. The SDK does not check the host, so a URL can point to a private or local address, such as https://10.0.0.5. A server-side application that resolves untrusted addresses must filter the hosts it connects to. When allowedRedirects is set, redirect targets are not checked. The Federation.Server constructor does not check the URL that you pass to it (#1809).
• Contract clients reject a muxed (M… or W…) address for an Address parameter; pass it to a MuxedAddress parameter instead. authorizeEntry(), authorizeInvocation() and buildWithDelegatesEntry() reject a muxed signer or delegate address. rpc.Server.getContractData() rejects a muxed owner and a key that contains a muxed address. rpc.Server.getAssetBalance() and getSACBalance() reject a muxed address, since balances are held by the base address. Before, each of these built a request that the network rejects or can never match (#1811, #1835).
• nativeToScVal() and Spec.nativeToScVal() throw a TypeError for a function value. Before, they called the function and converted its result. To keep the old result, call the function and pass its return value. Spec also treats a struct field named like an inherited Object.prototype function as missing when the value does not set it. Examples are toString and constructor. Before, contract clients encoded that field from the inherited function, for example toString as "[object Undefined]" (#1834).

Fixed

• toJson() on a MuxedEd25519Account, or on an ScAddress that holds one, throws when the ID is outside the uint64 range. Before, it wrapped the ID, so -1n gave an M… address with ID 2^64 - 1 and 2n ** 64n gave one with ID 0. toXdr() already threw for these IDs (#1811).
• CallBuilder.stream() passes an event that it cannot parse to onerror and keeps the stream open. onerror gets a MessageEvent of type "error" whose data is the parse error. The stream moves its cursor to the event's SSE id, so a reconnect does not get the event again. An onerror handler that closes the stream now also closes it on such an event. Before, the event listener threw the error as an uncaught exception, which stops a Node.js process that has no handler for it (#1806).
• Horizon records no longer get a link method whose name is then, toJSON, paging_token, _links or the name of an Object.prototype property, such as __proto__ or constructor. The link stays in _links. Before, a then link made call() hang while it sent requests in a loop. A toJSON link made JSON.stringify() return {} and send a request. A __proto__ link changed the record's prototype. A paging_token link made stream() reconnect with the link function's source code as its cursor. A _links link replaced _links with a function, so each link method after it threw (#1806).
• scValToNative() throws a TypeError when two keys of an scvMap convert to the same object property, such as u32 1 and symbol "1". It previously kept only the last entry. Maps whose keys all convert to distinct properties decode as before. Because any contract can emit such a map, humanizeEvents() and contract-client decoding of Val-typed values can now throw on data read from the network (#1778).
• Templated Horizon _links functions now resolve a relative href the same way non-templated links do. They previously threw TypeError: Invalid URL (#1771).
• MuxedAccount, encodeMuxedAccount() and Keypair.xdrMuxedAccount() accept an ID only as decimal digits. MuxedAccount returns the ID in canonical form from id(). Before, any string that BigInt() accepts passed, such as "0x10", " 16 " or "". id() returned that string as typed, so two objects for the same M-address could report different IDs, and an empty string silently became ID 0. An ID string longer than 22 characters is now rejected before it is parsed, so a very long string no longer costs CPU time and memory (#1780).
• Operation.manageSellOffer() and Operation.manageBuyOffer() accept offerId only as a non-negative safe integer, a non-negative bigint, or a string of decimal digits, up to the int64 maximum. Operation.revokeOfferSponsorship() applies the same rule, and now also accepts a number or a bigint offerId, such as the offerId of a decoded LedgerKeyOffer. Before, a number above 2^53 - 1 was rounded and could name a different offer. An empty string meant offer 0, and a negative ID built an operation that the network rejects. An offerId string longer than 22 characters is now rejected before it is parsed (#1780).
• TransactionBuilder.setTimeout(TimeoutInfinite) keeps an existing minTime. Before, it reset both time bounds to 0, so a transaction meant to become valid later was valid at once (#1781).
• new Asset(code, issuer) keeps an issued asset's code as given. It previously changed every spelling of xlm to XLM, even when an issuer was present. As a result, Asset.fromOperation() and transaction.operations showed XLM:G… for an operation on xlm:G…. Encoding the decoded asset again also changed its bytes. An asset built as new Asset("xlm", issuer) now encodes xlm, so its contract ID changes. To keep the old asset, pass XLM (#1784).
• Transaction and FeeBumpTransaction now decode their own copy of a TransactionEnvelope object passed to the constructor, to TransactionBuilder.fromXdr() or from TransactionBuilder.build(). Before, they kept the caller's object. A later change to that object altered what hash(), sign() and toXdr() used, but not always what operations showed. An envelope that cannot be encoded, such as one with more than 100 operations, now fails in the constructor and in TransactionBuilder.build(), not later in toXdr() or sign() (#1784).
• WebAuth.readChallengeTx(), verifyChallengeTxSigners() and verifyChallengeTxThreshold() throw an InvalidChallengeError when a challenge's client_domain operation has no source account. SEP-10 requires that source to be the client domain's signing key. The verifiers previously skipped the client domain signature check for such a challenge. (#1788)
• WebAuth.buildChallengeTx() throws when clientSigningKey is the server's public key. WebAuth.readChallengeTx(), verifyChallengeTxSigners() and verifyChallengeTxThreshold() throw InvalidChallengeError when the client_domain operation's source account is the server account. The server signature previously also counted as the client domain signature, and verifyChallengeTxSigners() could leave a valid client signer out of its result. (#1791)
• In Node, when maxRedirects is set, the Fetch client rejects a redirect to a URL that is not http: or https:. It also rejects a redirect from https: to http:. Before, it followed both. For example, StellarToml.Resolver.resolve() with allowedRedirects returned the content of a data: URL. When a redirect changes the method to GET, the client now also removes the Content-Encoding, Content-Language, Content-Location and Content-Range headers. (#1799)
• rpc.Server now applies its timeout option to each request. Before, the option was ignored, so a request to a server that did not answer stayed pending. This also fixes the --timeout flag of the bindings CLI, which had no effect (#1802).
• The Fetch client sends params when the URL has a # fragment. Before, it added them after the fragment, so the server did not receive them. When there are params, the fragment is now left out of the request URL, as in the Axios build (#1804).
• In Node, when maxRedirects is set, the Fetch client keeps only a safe set of headers on a redirect to another origin: Accept, Accept-Encoding, Accept-Language, Content-Type, Content-Length, Content-Encoding, Content-Language, Content-Location, Content-Range, User-Agent, Range, Cache-Control, Pragma, the If-* conditional headers, X-Client-Name, X-Client-Version, X-App-Name and X-App-Version. Other custom headers, such as traceparent, are dropped too. An http: to https: redirect on the same host counts as another origin. Before, the client removed only Authorization, Proxy-Authorization and Cookie. Other credential headers, such as the Horizon authToken (X-Auth-Token) or an API key in headers, reached the new origin. A redirect to the same origin keeps all headers (#1814).
• AssembledTransaction.sign() and signAndSend() keep the fee from simulation. Before, they added the Soroban resource fee to the fee a second time, which raised the inclusion fee bid. The automatic footprint restore now uses the fee option (or BASE_FEE) as the inclusion fee. Before, it used the restore's resource fee as the inclusion fee and ignored fee. Set fee to bid more during surge pricing. restoreFootprint() still accepts minResourceFee but does not use it (#1808).
• Contract client MuxedAddress parameters accept an Address object, as their string | Address type says. Before, they threw "was not address, but value was Address" (#1811).
• TransactionBuilder.build() throws for a Soroban transaction that has a muxed M… source account, on the transaction or on an operation, or that has a memo. addSacTransferOperation() throws as soon as it is called on a builder with a muxed source. The network rejects all of these, so the transaction could never succeed (#1811, #1835).
• In Node, and in the Fetch build in a browser, Federation.Server no longer follows redirects. Before, it followed up to 21 redirects in the Axios build and up to 20 in the Fetch build, although the v15.1.0 entry for #1390 listed a redirect guard for it. The Axios build in a browser, and both builds in React Native, still follow redirects, because XHR follows them itself. To follow redirects, set the new allowedRedirects option, as for StellarToml.Resolver.resolve(). createForDomain() and resolve() also apply it to the stellar.toml request. The constructor, createForDomain() and resolve() throw when allowedRedirects is not 0 or a whole number up to Number.MAX_SAFE_INTEGER, such as NaN, Infinity, -1, 1.5 or 2 ** 54 (#1809).
• Spec.parseEvent() matches a map event declaration only when the event data is an scvMap, and a vec declaration only when the data is an scvVec. Otherwise it tries the next declaration. Before, it treated other data as an empty map or vec. A map declaration then matched without its data params, so a single-value event declared later never matched. For example, a mint event with i128 data was returned as the map-format Mint without its amount, in place of MintWithAmountOnly. The generated bindings' event parsing method calls Spec.parseEvent(), so it has the same fix (#1817).
• TransactionBuilder.build(), TransactionBuilder.cloneFrom(), TransactionBuilder.buildFeeBumpTransaction() and rpc.assembleTransaction() throw when a Soroban resourceFee is below 0 or above 2^50. Before, a negative value raised the fee in cloneFrom() and assembleTransaction(), and build() made a transaction that the network rejects. When the resourceFee equals the fee, cloneFrom() and assembleTransaction() now use an inclusion fee of 0. Before, they counted the resource fee twice, so AssembledTransaction.sign() with fee: "0" signed 2 × the resource fee (#1832).
• authorizeEntry() replaces the other signatures of a SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES entry with scvVoid when validUntilLedgerSeq differs from a non-zero stored expiration. The top-level account and all delegates sign one payload that includes the expiration. Before, the call changed the stored expiration and kept the other signatures, which then did not verify. checkAuthEntryReadiness() now lists those signers in unsignedBy. When the stored expiration is 0, as simulation returns, authorizeEntry() keeps an ed25519 signature on another node only when it verifies at validUntilLedgerSeq. It keeps a custom signature as it is. AssembledTransaction.signAuthEntries() keeps the stored expiration of a SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES entry by default while it lies within the next 100 ledgers. So delegates that signed first keep their signatures. Every other entry gets the latest ledger + 100, as before. An explicit expiration still applies to every entry (#1830).
• The docs of the generated .value getter on string<N> union arms (xdr.Memo memoText, and xdr.ScVal scvString, scvSymbol and scvExecutableTag) now say that it decodes leniently: bytes that are not valid UTF-8 become U+FFFD, so a value rebuilt from .value can have different bytes. The arm field (.text, .str, .sym, .executableTag) keeps the bytes. The docs of XdrString and Memo.text() now say that a lone surrogate in a JS string encodes as U+FFFD with no error. The XdrString header comment also said that toString() renders the SEP-0051 escape form. That form comes from toJson() (#1824).
• The SDK throws "Expected at most one 'contractspecv0' section in wasm, found " when a Wasm has more than one contractspecv0 custom section. Empty sections count. This applies to contract.Spec.fromWasm(), to contract.Client.fromWasm(), fromWasmHash(), from() and deploy(), to BindingGenerator.fromWasm(), fromWasmHash() and fromContractId(), and to the bindings CLI. Before, the SDK used the first non-empty section and ignored the others. Other tools can read a different section, so they could show a different contract interface. SEP-48 stores the interface in one section. A section name with a leading byte-order mark no longer counts as contractspecv0, which matches wasmparser-based tools (#1827).

Full Changelog: v17.2.1...v17.3.0