Merge branch 'master' into update-simulateTransaction-api

.cargo/config.toml

@@ -1,7 +1,7 @@
 # paths = ["/path/to/override"] # path dependency overrides
 
 [alias] # command aliases
-install_soroban = "install --version 20.2.0 --root ./target soroban-cli --debug"
+install_soroban = "install --version 21.0.0-preview.1 --root ./target soroban-cli --debug"
 # b = "build --target wasm32-unknown-unknown --release"
 # c = "check"
 # t = "test"

.eslintrc.js

@@ -2,9 +2,12 @@ module.exports = {
   env: {
     es6: true,
   },
-  extends: ["airbnb-base", "prettier"],
+  extends: [
+    "airbnb-base",
+    "prettier",
+    "plugin:jsdoc/recommended",
+  ],
   plugins: ["@babel", "prettier", "prefer-import"],
-  parser: "@typescript-eslint/parser",
   rules: {
     "node/no-unpublished-require": 0,
   },

.github/workflows/e2e.yml

@@ -1,4 +1,4 @@
-name: ContractClient
+name: e2e
 
 on:
   push:
@@ -7,17 +7,18 @@ on:
 
 jobs:
   test:
-    name: test generated ContractClient
+    name: test contract.Client
     runs-on: ubuntu-22.04
     services:
       rpc:
-        image: stellar/quickstart:soroban-dev@sha256:0ad51035cf7caba2fd99c7c1fad0945df6932be7d5c893e1520ccdef7d6a6ffe
+        image: stellar/quickstart:testing@sha256:bef5c451e305c914e91964ec22e7a25b9f5276a706fe0357ac23125569d93f05
         ports:
           - 8000:8000
         env:
           ENABLE_LOGS: true
           NETWORK: local
           ENABLE_SOROBAN_RPC: true
+          PROTOCOL_VERSION: 21
         options: >-
           --health-cmd "curl --no-progress-meter --fail-with-body -X POST \"http://localhost:8000/soroban/rpc\" -H 'Content-Type: application/json' -d '{\"jsonrpc\":\"2.0\",\"id\":8675309,\"method\":\"getNetwork\"}' && curl --no-progress-meter \"http://localhost:8000/friendbot\" | grep '\"invalid_field\": \"addr\"'"
           --health-interval 10s

.github/workflows/npm_publish.yml

@@ -22,6 +22,8 @@ jobs:
 
       - name: Build, Test, and Package
         run: yarn preversion
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
       - name: Publish npm package to both places
         run: |

CHANGELOG.md

@@ -11,16 +11,96 @@ Added:
 - Add stateChanges in SimulateTransaction API response ([#963](https://github.com/stellar/js-stellar-sdk/pull/963))
 
 
-## [v12.0.0](https://github.com/stellar/js-stellar-sdk/compare/v11.3.0...v12.0.0)
+## [v12.0.0-rc.3](https://github.com/stellar/js-stellar-sdk/compare/v11.3.0...v12.0.0-rc.3)
 
 ### Breaking Changes
-* **This update supports Protocol 21** ([#949](https://github.com/stellar/js-stellar-sdk/pull/949)).
+
+- `ContractClient` functionality previously added in [v11.3.0](https://github.com/stellar/js-stellar-sdk/releases/tag/v11.3.0) was exported in a non-standard way. You can now import it as any other `stellar-sdk` module ([#962](https://github.com/stellar/js-stellar-sdk/pull/962)):
+
+```diff
+-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](https://github.com/stellar/js-stellar-base/blob/b96281b9b3f94af23a913f93bdb62477f5434ccc/src/contract.js#L6-L19). 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](https://stackoverflow.com/a/70020984/249801) support [the `exports` declaration](https://nodejs.org/api/packages.html#exports). Finally, some of its exports have been renamed:
+
+```diff
+import {
+-  ContractClient,
++  Client,
+   AssembledTransaction,
+-  ContractClientOptions,
++  ClientOptions,
+   SentTransaction,
+-} from '@stellar/stellar-sdk/lib/contract_client'
++} from '@stellar/stellar-sdk/contract'
+```
+
+- The `ContractSpec` class is now nested under the `contract` module, and has been **renamed** to `Spec` ([#962](https://github.com/stellar/js-stellar-sdk/pull/962)). Alternatively, you can import this from the `contract` entrypoint, if your version of Node [and TypeScript](https://stackoverflow.com/a/70020984/249801) support [the `exports` declaration](https://nodejs.org/api/packages.html#exports):
+
+```diff
+-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 a `SentTransaction` even if the transaction never finalized. That is, if it successfully sent the transaction to the network, but the transaction was still `status: 'PENDING'`, then it would `console.error` an error message, but return the indeterminate transaction anyhow. **It now throws** a `SentTransaction.Errors.TransactionStillPending` error with that error message instead ([#962](https://github.com/stellar/js-stellar-sdk/pull/962)).
+
+### Deprecated
+
+- `SorobanRpc` module is now also exported as `rpc` ([#962](https://github.com/stellar/js-stellar-sdk/pull/962)). You can import it with either name for now, but `SorobanRpc` will be removed in a future release:
+
+```diff
+-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](https://stackoverflow.com/a/70020984/249801) support [the `exports` declaration](https://nodejs.org/api/packages.html#exports).
+
+```diff
+-import { SorobanRpc } from '@stellar/stellar-sdk'
+-const { Api } = SorobanRpc
++import { Api } from '@stellar/stellar-sdk/rpc'
+```
+
+### Added
+* New methods on `contract.Client` ([#960](https://github.com/stellar/js-stellar-sdk/pull/960)):
+  - `from(opts: ContractClientOptions)` instantiates `contract.Client` by fetching the `contractId`'s WASM from the network to fill out the client's `ContractSpec`.
+  - `fromWasm` and `fromWasmHash` methods to instantiate a `contract.Client` when you already have the WASM bytes or hash alongside the `contract.ClientOptions`.
+* New methods on `rpc.Server` ([#960](https://github.com/stellar/js-stellar-sdk/pull/960)):
+  - `getContractWasmByContractId` and `getContractWasmByHash` to retrieve a contract's WASM bytecode via its `contractId` or `wasmHash`, 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.
+
+
+## [v12.0.0-rc.2](https://github.com/stellar/js-stellar-sdk/compare/v11.3.0...v12.0.0-rc.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](https://github.com/stellar/js-stellar-sdk/pull/949)).
+
+### 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](https://github.com/stellar/js-stellar-sdk/pull/956)).
+
+### Fixed
+* Dependencies have been properly updated to pull in Protocol 21 XDR ([#959](https://github.com/stellar/js-stellar-sdk/pull/959)).
+
+
+## [v12.0.0-rc.1](https://github.com/stellar/js-stellar-sdk/compare/v11.3.0...v12.0.0-rc.1)
+
+### 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](https://github.com/stellar/js-stellar-sdk/pull/949)).
 
 ### Fixed
 * Each item in the `GetEventsResponse.events` list will now have a `txHash` item corresponding to the transaction hash that triggered a particular event ([#939](https://github.com/stellar/js-stellar-sdk/pull/939)).
 * `ContractClient` now properly handles methods that take no arguments by making `MethodOptions` the only parameter, bringing it inline with the types generated by Soroban CLI's `soroban contract bindings typescript` ([#940](https://github.com/stellar/js-stellar-sdk/pull/940)).
 * `ContractClient` now allows `publicKey` to be undefined ([#941](https://github.com/stellar/js-stellar-sdk/pull/941)).
-
+* `SentTransaction` will only pass `allowHttp` if (and only if) its corresponding `AssembledTransaction#options` config allowed it ([#952](https://github.com/stellar/js-stellar-sdk/pull/952)).
+* `SentTransaction` will now modify the time bounds of the transaction to be `timeoutInSeconds` seconds after the transaction has been simulated. Previously this was set when the transaction is built, before the simulation. This makes the time bounds line up with the timeout retry logic in `SentTransaction`.
 
 ## [v11.3.0](https://github.com/stellar/js-stellar-sdk/compare/v11.2.2...v11.3.0)
 

README.md

@@ -96,7 +96,7 @@ The usage documentation for this library lives in a handful of places:
 You can also refer to:
 
  * the [documentation](https://developers.stellar.org/network/horizon) for the Horizon REST API (if using the `Horizon` module) and
- * the [documentation](https://soroban.stellar.org/docs/reference/rpc) for Soroban RPC's API (if using the `SorobanRpc` module)
+ * the [documentation](https://soroban.stellar.org/docs/reference/rpc) for Soroban RPC's API (if using the `rpc` module)
 
 ### Usage with React-Native
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stellar/stellar-sdk",
-  "version": "12.0.0",
+  "version": "12.0.0-rc.3",
   "description": "A library for working with the Stellar network, including communication with the Horizon and Soroban RPC servers.",
   "keywords": [
     "stellar"
@@ -23,6 +23,21 @@
     "/lib",
     "/dist"
   ],
+  "exports": {
+    ".": {
+      "browser": "./dist/stellar-sdk.min.js",
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./contract": {
+      "types": "./lib/contract/index.d.ts",
+      "default": "./lib/contract/index.js"
+    },
+    "./rpc": {
+      "types": "./lib/rpc/index.d.ts",
+      "default": "./lib/rpc/index.js"
+    }
+  },
   "scripts": {
     "build": "cross-env NODE_ENV=development yarn _build",
     "build:prod": "cross-env NODE_ENV=production yarn _build",
@@ -39,7 +54,7 @@
     "test:integration": "yarn _nyc mocha --recursive 'test/integration/**/*.js'",
     "test:browser": "karma start config/karma.conf.js",
     "fmt": "yarn eslint -c .eslintrc.js src/ --fix && yarn _prettier",
-    "preversion": "yarn clean && yarn fmt && yarn build:prod && yarn test",
+    "preversion": "yarn clean && yarn _prettier && yarn build:prod && yarn test",
     "prepare": "yarn build:prod",
     "_build": "yarn build:node && yarn build:test && yarn build:browser",
     "_babel": "babel --extensions '.ts' --out-dir lib/ src/",
@@ -109,8 +124,10 @@
     "dotenv": "^16.4.5",
     "eslint": "^8.57.0",
     "eslint-config-airbnb-base": "^15.0.0",
+    "eslint-config-airbnb-typescript": "^18.0.0",
     "eslint-config-prettier": "^9.0.0",
     "eslint-plugin-import": "^2.29.1",
+    "eslint-plugin-jsdoc": "^48.2.4",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prefer-import": "^0.0.1",
     "eslint-plugin-prettier": "^5.1.2",
@@ -145,7 +162,7 @@
     "webpack-cli": "^5.0.1"
   },
   "dependencies": {
-    "@stellar/stellar-base": "^11.0.1",
+    "@stellar/stellar-base": "^12.0.0-rc.1",
     "axios": "^1.6.8",
     "bignumber.js": "^9.1.2",
     "eventsource": "^2.0.2",

src/.eslintrc.js

@@ -1,6 +1,13 @@
 module.exports = {
-  env: {
-    es6: true,
+  extends: [
+    "airbnb-base",
+    "airbnb-typescript/base",
+    "prettier",
+    "plugin:jsdoc/recommended",
+  ],
+  parserOptions: {
+    parser: "@typescript-eslint/parser",
+    project: "./config/tsconfig.json",
   },
   rules: {
     // OFF
@@ -10,6 +17,8 @@ module.exports = {
     camelcase: 0,
     "class-methods-use-this": 0,
     "linebreak-style": 0,
+    "jsdoc/require-returns": 0,
+    "jsdoc/require-param": 0,
     "new-cap": 0,
     "no-param-reassign": 0,
     "no-underscore-dangle": 0,
@@ -18,19 +27,12 @@ module.exports = {
     "lines-between-class-members": 0,
 
     // WARN
-    "prefer-import/prefer-import-over-require": [1],
+    "arrow-body-style": 1,
     "no-console": ["warn", { allow: ["assert"] }],
     "no-debugger": 1,
-    "no-unused-vars": 1,
-    "arrow-body-style": 1,
-    "valid-jsdoc": [
-      1,
-      {
-        requireReturnDescription: false,
-      },
-    ],
-    "prefer-const": 1,
     "object-shorthand": 1,
+    "prefer-const": 1,
+    "prefer-import/prefer-import-over-require": [1],
     "require-await": 1,
 
     // ERROR