Releases: stellar/js-stellar-sdk
v12.0.1
v12.0.1: Protocol 21 Stable Release
This update supports Protocol 21. It is an additive change to the protocol so there are no binary (i.e. XDR-level) incompatibilities, but your software may break if you encounter new unexpected or renamed fields from this Protocol (#949).
The following changelog is a concatenation of all of the RCs since the previous stable release and includes one additional added feature.
Breaking Changes
- The default timeout for transaction calls is now set to 300 seconds (5 minutes) when using
ContractClient
from the previous default of 10 seconds. 10 seconds is often not enough time to review transactions before signing, especially in Freighter or using a hardware wallet like a Ledger, which would cause atxTooLate
error response from the server. Five minutes is also the value used by the CLI, so this brings the two into alignment (#956). ContractClient
functionality previously added in v11.3.0 was exported in a non-standard way. You can now import it as any otherstellar-sdk
module (#962):
-import { ContractClient } from '@stellar/stellar-sdk/lib/contract_client'
+import { contract } from '@stellar/stellar-sdk'
+const { Client } = contract
Note that this top-level contract
export is a container for ContractClient and related functionality. The ContractClient
class is now available at contract.Client
, as shown. Further note that there is a capitalized Contract
export as well, which comes from stellar-base. You can remember which is which because capital-C Contract
is a class, whereas lowercase-c contract
is a container/module with a bunch of classes, functions, and types.
Additionally, this is available from the /contract
entrypoint, if your version of Node and TypeScript support the exports
declaration. Finally, some of its exports have been renamed:
import {
AssembledTransaction,
SentTransaction,
- ContractClient,
- ContractClientOptions,
-} from '@stellar/stellar-sdk/lib/contract_client'
+ Client,
+ ClientOptions,
+} from '@stellar/stellar-sdk/contract'
- The
ContractSpec
class is now nested under thecontract
module, and has been renamed toSpec
(#962). Alternatively, you can import this from thecontract
entrypoint, if your version of Node and TypeScript support theexports
declaration:
-import { ContractSpec } from '@stellar/stellar-sdk'
+import { contract } from '@stellar/stellar-sdk'
+const { Spec } = contract
// OR
+import { Spec } from '@stellar/stellar-sdk/contract'
- Previously,
AssembledTransaction.signAndSend()
would return aSentTransaction
even if the transaction never finalized. That is, if it successfully sent the transaction to the network, but the transaction was stillstatus: 'PENDING'
, then it wouldconsole.error
an error message, but return the indeterminate transaction anyhow. It now throws aSentTransaction.Errors.TransactionStillPending
error with that error message instead (#962).
Deprecated
SorobanRpc
module is now also exported asrpc
(#962). You can import it with either name for now, butSorobanRpc
will be removed in a future release:
-import { SorobanRpc } from '@stellar/stellar-sdk'
+import { rpc } from '@stellar/stellar-sdk'
You can also now import it at the /rpc
entrypoint, if your version of Node and TypeScript support the exports
declaration.
-import { SorobanRpc } from '@stellar/stellar-sdk'
-const { Api } = SorobanRpc
+import { Api } from '@stellar/stellar-sdk/rpc'
Added
- New methods on
contract.Client
(#960):from(opts: ContractClientOptions)
instantiatescontract.Client
by fetching thecontractId
's WASM from the network to fill out the client'sContractSpec
.fromWasm
andfromWasmHash
methods to instantiate acontract.Client
when you already have the WASM bytes or hash alongside thecontract.ClientOptions
.
- New methods on
rpc.Server
(#960):getContractWasmByContractId
andgetContractWasmByHash
to retrieve a contract's WASM bytecode via itscontractId
orwasmHash
, respectively.
rpc.server.simulateTransaction
now supports an optionalstateChanges?: LedgerEntryChange[]
field (#963):- If
Before
is omitted, it constitutes a creation, ifAfter
is omitted, it constitutes a deletions, note thatBefore
andAfter
cannot be be omitted at the same time. Each item follows this schema:
- If
interface LedgerEntryChange {
type: number;
key: xdr.LedgerKey;
before: xdr.LedgerEntry | null;
after: xdr.LedgerEntry | null;
}
Fixed
- The breaking changes above (strictly speaking, they are not breaking changes because importing from the inner guts of the SDK is not supported) enable the
contract
module to be used in non-Node environments. - Dependencies have been properly updated to pull in Protocol 21 XDR, where RC1 was not pulling properly for existing installs (#959).
- Each item in the
GetEventsResponse.events
list will now have atxHash
item corresponding to the transaction hash that triggered a particular event (#939). ContractClient
now properly handles methods that take no arguments by makingMethodOptions
the only parameter, bringing it inline with the types generated by Soroban CLI'ssoroban contract bindings typescript
(#940).ContractClient
now allowspublicKey
to be undefined (#941).SentTransaction
will only passallowHttp
if (and only if) its correspondingAssembledTransaction#options
config allowed it (#952).
New Contributors
- @silence48 made their first contribution in #934
- @BlaineHeffron made their first contribution in #951
- @psheth9 made their first contribution in #963
Full Changelog: v11.3.0...v12.0.1
v12.0.0-rc.3
v12.0.0-rc.3: Protocol 21 Release Candidate 3
This update supports Protocol 21. It is an additive change to the protocol so there are no true backwards incompatibilities, but your software may break if you encounter new unexpected fields from this Protocol (#949).
Breaking Changes
ContractClient
functionality previously added in v11.3.0 was exported in a non-standard way. You can now import it as any otherstellar-sdk
module (#962):
-import { ContractClient } from '@stellar/stellar-sdk/lib/contract_client'
+import { contract } from '@stellar/stellar-sdk'
+const { Client } = contract
Note that this top-level contract
export is a container for ContractClient and related functionality. The ContractClient
class is now available at contract.Client
, as shown. Further note that there is a capitalized Contract
export as well, which comes from stellar-base. You can remember which is which because capital-C Contract
is a class, whereas lowercase-c contract
is a container/module with a bunch of classes, functions, and types.
Additionally, this is available from the /contract
entrypoint, if your version of Node and TypeScript support the exports
declaration. Finally, some of its exports have been renamed:
import {
AssembledTransaction,
SentTransaction,
- ContractClient,
- ContractClientOptions,
-} from '@stellar/stellar-sdk/lib/contract_client'
+ Client,
+ ClientOptions,
+} from '@stellar/stellar-sdk/contract'
- The
ContractSpec
class is now nested under thecontract
module, and has been renamed toSpec
(#962). Alternatively, you can import this from thecontract
entrypoint, if your version of Node and TypeScript support theexports
declaration:
-import { ContractSpec } from '@stellar/stellar-sdk'
+import { contract } from '@stellar/stellar-sdk'
+const { Spec } = contract
// OR
+import { Spec } from '@stellar/stellar-sdk/contract'
- Previously,
AssembledTransaction.signAndSend()
would return aSentTransaction
even if the transaction never finalized. That is, if it successfully sent the transaction to the network, but the transaction was stillstatus: 'PENDING'
, then it wouldconsole.error
an error message, but return the indeterminate transaction anyhow. It now throws aSentTransaction.Errors.TransactionStillPending
error with that error message instead (#962).
Deprecated
SorobanRpc
module is now also exported asrpc
(#962). You can import it with either name for now, butSorobanRpc
will be removed in a future release:
-import { SorobanRpc } from '@stellar/stellar-sdk'
+import { rpc } from '@stellar/stellar-sdk'
You can also now import it at the /rpc
entrypoint, if your version of Node and TypeScript support the exports
declaration.
-import { SorobanRpc } from '@stellar/stellar-sdk'
-const { Api } = SorobanRpc
+import { Api } from '@stellar/stellar-sdk/rpc'
Added
- New methods on
contract.Client
(#960):from(opts: ContractClientOptions)
instantiatescontract.Client
by fetching thecontractId
's WASM from the network to fill out the client'sContractSpec
.fromWasm
andfromWasmHash
methods to instantiate acontract.Client
when you already have the WASM bytes or hash alongside thecontract.ClientOptions
.
- New methods on
rpc.Server
(#960):getContractWasmByContractId
andgetContractWasmByHash
to retrieve a contract's WASM bytecode via itscontractId
orwasmHash
, respectively.
Fixed
- The breaking changes above (strictly speaking, they are not breaking changes because importing from the inner guts of the SDK is not supported) enable the
contract
module to be used in non-Node environments.
Full Changelog: v11.3.0...v12.0.0-rc.3
v12.0.0-rc.2
v12.0.0-rc.2: Protocol 21 Release Candidate 2
This update supports Protocol 21. It is an additive change to the protocol so there are no true backwards incompatibilities, but your software may break if you encounter new unexpected fields from this Protocol (#949).
Please refer to RC1 for additional changes since the last major version.
Breaking Changes
- The default timeout for transaction calls is now set to 300 seconds (5 minutes) from the previous default of 10 seconds. 10 seconds is often not enough time to review transactions before signing, especially in Freighter or using a hardware wallet like a Ledger, which would cause a
txTooLate
error response from the server. Five minutes is also the value used by the CLI, so this brings the two into alignment (#956).
Fixed
- Dependencies have been properly updated to pull in Protocol 21 XDR, where RC1 was not pulling properly for existing installs (#959).
New Contributors
- @BlaineHeffron made their first contribution in #951
Full Changelog: v11.3.0...v12.0.0-rc.2
v12.0.0-rc.1
v12.0.0-rc.1: Protocol 21 Release Candidate
Breaking Changes
- This update supports Protocol 21. It is an additive change to the protocol so there are no true backwards incompatibilities, but your software may break if you encounter new unexpected fields from this Protocol (#949).
Fixed
- Each item in the
GetEventsResponse.events
list will now have atxHash
item corresponding to the transaction hash that triggered a particular event (#939). ContractClient
now properly handles methods that take no arguments by makingMethodOptions
the only parameter, bringing it inline with the types generated by Soroban CLI'ssoroban contract bindings typescript
(#940).ContractClient
now allowspublicKey
to be undefined (#941).SentTransaction
will only passallowHttp
if (and only if) its correspondingAssembledTransaction#options
config allowed it (#952).
New Contributors
- @silence48 made their first contribution in #934
Full Changelog: v11.3.0...v12.0.0-rc.1
v11.3.0
Added
- Introduces an entire suite of helpers to assist with interacting with smart contracts (#929):
ContractClient
: generate a class from the contract specification where each Rust contract method gets a matching method in this class. Each method returns anAssembledTransaction
that can be used to modify, simulate, decode results, and possibly sign, & submit the transaction.AssembledTransaction
: used to wrap a transaction-under-construction and provide high-level interfaces to the most common workflows, while still providing access to low-level transaction manipulation.SentTransaction
: transaction sent to the Soroban network, in two steps - initial submission and waiting for it to finalize to get the result (retried with exponential backoff)
Fixed
- Upgrade underlying dependencies, including
@stellar/js-xdr
which should broaden compatibility to pre-ES2016 environments (#932, #930). SorobanRpc.Server
will no longer use array-based passing to invoke JSON-RPC methods (#924).
Full Changelog: v11.2.2...v11.3.0
v11.2.2
v11.2.1
v11.2.0
Added
- Support for the new, optional
diagnosticEventsXdr
field on theSorobanRpc.Server.sendTransaction
method. The raw field will be present when using the_sendTransaction
method, while the normal method will have an already-parseddiagnosticEvents: xdr.DiagnosticEvent[]
field, instead (#905). - A new exported interface
SorobanRpc.Api.EventResponse
so that developers can type-check individual events (#904).
Updated
v11.1.0
Added
SorobanRpc.Server.simulateTransaction
now supports an optionaladdlResources
parameter to allow users to specify additional resources that they want to include in a simulation (#896).ContractSpec
now has ajsonSchema()
method to generate a JSON Schema for a particular contract specification (#889).
Fixed
- All dependencies have been updated to their latest versions, including
stellar-base
to v10.0.1 which included a small patch (#897).
New Contributors
- @willemneal made their first contribution in #889
Full Changelog: v11.0.1...v11.1.0