@stellar/stellar-sdk 11.0.1 → 11.2.0

package/CHANGELOG.md

@@ -1,8 +1,32 @@
+
 # Changelog
 
 A breaking change will get clearly marked in this log.
 
 
+## Unreleased
+
+
+## [v11.2.0](https://github.com/stellar/js-stellar-sdk/compare/v11.1.0...v11.2.0)
+
+### Added
+* Support for the new, optional `diagnosticEventsXdr` field on the `SorobanRpc.Server.sendTransaction` method. The raw field will be present when using the `_sendTransaction` method, while the normal method will have an already-parsed `diagnosticEvents: xdr.DiagnosticEvent[]` field, instead ([#905](https://github.com/stellar/js-stellar-sdk/pull/905)).
+* A new exported interface `SorobanRpc.Api.EventResponse` so that developers can type-check individual events ([#904](https://github.com/stellar/js-stellar-sdk/pull/904)).
+
+### Updated
+* Dependencies have been updated to their latest versions ([#906](https://github.com/stellar/js-stellar-sdk/pull/906), [#908](https://github.com/stellar/js-stellar-sdk/pull/908)).
+
+
+## [v11.1.0](https://github.com/stellar/js-stellar-sdk/compare/v11.0.1...v11.1.0)
+
+### Added
+* `SorobanRpc.Server.simulateTransaction` now supports an optional `addlResources` parameter to allow users to specify additional resources that they want to include in a simulation ([#896](https://github.com/stellar/js-stellar-sdk/pull/896)).
+* `ContractSpec` now has a `jsonSchema()` method to generate a [JSON Schema](https://json-schema.org/) for a particular contract specification ([#889](https://github.com/stellar/js-stellar-sdk/pull/889)).
+
+### Fixed
+* All dependencies have been updated to their latest versions, including `stellar-base` to [v10.0.1](https://github.com/stellar/js-stellar-base/releases/tag/v10.0.1) which included a small patch ([#897](https://github.com/stellar/js-stellar-sdk/pull/897)).
+
+
 ## [v11.0.1](https://github.com/stellar/js-stellar-sdk/compare/v10.2.1...v11.0.0)
 
 ### Fixed

package/README.md

@@ -1,3 +1,4 @@
+
 <div align="center">
   <img alt="Stellar" src="https://github.com/stellar/.github/raw/master/stellar-logo.png" width="558" />
   <br/>
@@ -13,162 +14,89 @@
   <a href="https://github.com/stellar/js-stellar-sdk/actions/workflows/tests.yml"><img alt="Test Status" src="https://github.com/stellar/js-stellar-sdk/actions/workflows/tests.yml/badge.svg" /></a>
 </p>
 
-js-stellar-sdk is a Javascript library for communicating with a
-[Stellar Horizon server](https://github.com/stellar/go/tree/master/services/horizon).
-It is used for building Stellar apps either on Node.js or in the browser.
+js-stellar-sdk is a JavaScript library for communicating with a
+[Stellar Horizon server](https://github.com/stellar/go/tree/master/services/horizon) and [Soroban RPC](https://soroban.stellar.org/docs/reference/rpc).
+It is used for building Stellar apps either on Node.js or in the browser, though it can be used in other environments with some tinkering.
 
 It provides:
 
-- a networking layer API for Horizon endpoints.
+- a networking layer API for Horizon endpoints (REST-based),
+- a networking layer for Soroban RPC (JSONRPC-based).
 - facilities for building and signing transactions, for communicating with a
   Stellar Horizon instance, and for submitting transactions or querying network
   history.
 
-### stellar-sdk vs stellar-base
-
-stellar-sdk is a high-level library that serves as client-side API for Horizon.
-[stellar-base](https://github.com/stellar/js-stellar-base) is lower-level
-library for creating Stellar primitive constructs via XDR helpers and wrappers.
-
-**Most people will want stellar-sdk instead of stellar-base.** You should only
-use stellar-base if you know what you're doing!
-
-If you add `stellar-sdk` to a project, **do not add `stellar-base`!** Mis-matching
-versions could cause weird, hard-to-find bugs. `stellar-sdk` automatically
-installs `stellar-base` and exposes all of its exports in case you need them.
-
-> **Important!** The Node.js version of the `stellar-base` (`stellar-sdk` dependency) package
-> uses the [`sodium-native`](https://www.npmjs.com/package/sodium-native) package as
-> an [optional dependency](https://docs.npmjs.com/files/package.json#optionaldependencies). `sodium-native` is
-> a low level binding to [libsodium](https://github.com/jedisct1/libsodium),
-> (an implementation of [Ed25519](https://ed25519.cr.yp.to/) signatures).
-> If installation of `sodium-native` fails, or it is unavailable, `stellar-base` (and `stellar-sdk`) will
-> fallback to using the [`tweetnacl`](https://www.npmjs.com/package/tweetnacl) package implementation.
->
-> If you are using `stellar-sdk`/`stellar-base` in a browser you can ignore
-> this. However, for production backend deployments you should be
-> using `sodium-native`. If `sodium-native` is successfully installed and working the
-> `StellarSdk.FastSigning` variable will return `true`.
-
-## Quick start
-
-Using npm to include js-stellar-sdk in your own project:
-
-```shell
-npm install --save stellar-sdk
-```
-
-Alternatively, you can use cdnjs in a browser:
-
-```html
-<script src="https://cdnjs.cloudflare.com/ajax/libs/stellar-sdk/{version}/stellar-sdk.js"></script>
-````
+**Jump to:**
 
-## Install
+ * [Installation](#installation): details on hitting the ground running
+ * [Usage](#usage): links to documentation and a variety of workarounds for non-traditional JavaScript environments
+   - [...with React Native](#usage-with-react-native)
+   - [...with Expo](#usage-with-expo-managed-workflows)
+   - [...with CloudFlare Workers](#usage-with-cloudflare-workers)
+ * [Developing](#developing): contribute to the project!
+ * [Understanding `stellar-sdk` vs. `stellar-base`](#stellar-sdk-vs-stellar-base)
+ * [License](#license)
 
-### To use as a module in a Node.js project
+## Installation
 
-1. Install it using npm:
+Using npm or yarn to include `stellar-sdk` in your own project:
 
 ```shell
-npm install --save stellar-sdk
+npm install --save @stellar/stellar-sdk
+# or
+yarn add @stellar/stellar-sdk
 ```
 
-2. require/import it in your JavaScript:
+Then, require or import it in your JavaScript code:
 
 ```js
-var StellarSdk = require('stellar-sdk');
+var StellarSdk = require('@stellar/stellar-sdk');
+// or
+import * as StellarSdk from '@stellar/stellar-sdk';
 ```
 
-### To self host for use in the browser
-
-1. Install it using [bower](http://bower.io):
+(Preferably, you would only import the pieces you need to enable tree-shaking and lower your final bundle sizes.)
 
-```shell
-bower install stellar-sdk
-```
+### Browsers
 
-2. Include it in the browser:
+You can use a CDN:
 
 ```html
-<script src="./bower_components/stellar-sdk/stellar-sdk.js"></script>
-<script>
-  console.log(StellarSdk);
-</script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/stellar-sdk/{version}/stellar-sdk.js"></script>
 ```
 
-If you don't want to use or install Bower, you can copy built JS files from the
-[bower-js-stellar-sdk repo](https://github.com/stellar/bower-js-stellar-sdk).
+Note that this method relies using a third party to host the JS library. This may not be entirely secure. You can self-host it via [Bower](http://bower.io):
 
-### To use the [cdnjs](https://cdnjs.com/libraries/stellar-sdk) hosted script in the browser
+```shell
+bower install @stellar/stellar-sdk
+```
 
-1. Instruct the browser to fetch the library from
-   [cdnjs](https://cdnjs.com/libraries/stellar-sdk), a 3rd party service that
-   hosts js libraries:
+and include it in the browser:
 
 ```html
-<script src="https://cdnjs.cloudflare.com/ajax/libs/stellar-sdk/{version}/stellar-sdk.js"></script>
+<script src="./bower_components/stellar-sdk/stellar-sdk.js"></script>
 <script>
   console.log(StellarSdk);
 </script>
 ```
 
-Note that this method relies using a third party to host the JS library. This
-may not be entirely secure.
-
-Make sure that you are using the latest version number. They can be found on the
-[releases page in Github](https://github.com/stellar/js-stellar-sdk/releases).
-
-### To develop and test js-stellar-sdk itself
-
-1. Clone the repo:
-
-```shell
-git clone https://github.com/stellar/js-stellar-sdk.git
-```
-
-2. Install dependencies inside js-stellar-sdk folder:
-
-```shell
-cd js-stellar-sdk
-npm install
-```
-
-3. Install Node 16
-
-Because we support the oldest maintenance version of Node, please install and develop on Node 16 so you don't get surprised when your code works locally but breaks in CI.
-
-Here's how to install `nvm` if you haven't: https://github.com/creationix/nvm
-
-```shell
-nvm install
-
-# if you've never installed 16 before you'll want to re-install yarn
-npm install -g yarn
-```
-
-If you work on several projects that use different Node versions, you might it
-helpful to install this automatic version manager:
-https://github.com/wbyoung/avn
-
-4. Observe the project's code style
+If you don't want to use or install Bower, you can copy the packaged JS files from the [Bower repo](https://github.com/stellar/bower-js-stellar-sdk), or just build the package yourself locally (see [Developing :arrow_right: Building](#building)) and copy the bundle.
 
-While you're making changes, make sure to run the linter-watcher to catch any
-   linting errors (in addition to making sure your text editor supports ESLint)
+| Always make sure that you are using the latest version number. They can be found on the [releases page](https://github.com/stellar/js-stellar-sdk/releases) in GitHub. |
+|----|
 
-```shell
-node_modules/.bin/gulp watch
-```
+## Usage
 
+The usage documentation for this library lives in a handful of places:
 
-## Usage
+ * across the [Stellar Developer Docs](), which includes tutorials and examples,
+ * within [this repository itself](https://github.com/stellar/js-stellar-sdk/blob/master/docs/reference/readme.md), and
+ * on the generated [API doc site](https://stellar.github.io/js-stellar-sdk/).
 
-For information on how to use js-stellar-sdk, take a look at [the
-documentation](https://stellar.github.io/js-stellar-sdk/), or [the
-examples](https://github.com/stellar/js-stellar-sdk/tree/master/docs/reference).
+You can also refer to:
 
-There is also Horizon REST API Documentation
-[here](https://developers.stellar.org/api/introduction/).
+ * the [documentation](https://developers.stellar.org/api/introduction/) 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)
 
 ### Usage with React-Native
 
@@ -188,11 +116,11 @@ module.exports = {
 };
 ```
 6. Add `import "./shim";` to the top of `index.js`
-7. `yarn add stellar-sdk`
+7. `yarn add @stellar/stellar-sdk`
 
 There is also a [sample](https://github.com/fnando/rn-stellar-sdk-sample) that you can follow.
 
-#### Using in an Expo managed workflow
+#### Usage with Expo managed workflows
 
 1. Install `yarn add --dev rn-nodeify`
 2. Add the following postinstall script:
@@ -200,23 +128,111 @@ There is also a [sample](https://github.com/fnando/rn-stellar-sdk-sample) that y
 yarn rn-nodeify --install process,url,events,https,http,util,stream,crypto,vm,buffer --hack --yarn
 ```
 3. Add `import "./shim";` to the your app's entry point (by default `./App.js`)
-4. `yarn add stellar-sdk`
+4. `yarn add @stellar/stellar-sdk`
 5. `expo install expo-random`
 
 At this point, the Stellar SDK will work, except that `StellarSdk.Keypair.random()` will throw an error. To work around this, you can create your own method to generate a random keypair like this:
 
 ```javascript
 import * as Random from 'expo-random';
-import StellarSdk from 'stellar-sdk';
+import { Keypair } from '@stellar/stellar-sdk';
 
 const generateRandomKeypair = () => {
   const randomBytes = Random.getRandomBytes(32);
-
-  return StellarSdk.Keypair.fromRawEd25519Seed(Buffer.from(randomBytes));
+  return Keypair.fromRawEd25519Seed(Buffer.from(randomBytes));
 };
 ```
 
-## Testing
+#### Usage with CloudFlare Workers
+
+Both `eventsource` (needed for streaming) and `axios` (needed for making HTTP requests) are problematic dependencies in the CFW environment. The experimental branch [`make-eventsource-optional`](https://github.com/stellar/js-stellar-sdk/pull/901) is an attempt to resolve these issues.
+
+It requires the following additional tweaks to your project:
+ * the `axios-fetch-adapter` lets you use `axios` with `fetch` as a backend, which is available to CF workers
+ * it only works with `axios@"<= 1.0.0"` versions, so we need to force an override into the underlying dependency
+ * and this can be problematic with newer `yarn` versions, so we need to force the environment to use Yarn 1
+
+In summary, the `package.json` tweaks look something like this:
+
+```jsonc
+"dependencies": {
+  // ...
+  "@stellar/stellar-sdk": "git+https://github.com/stellar/js-stellar-sdk#make-eventsource-optional",
+  "@vespaiach/axios-fetch-adapter": "^0.3.1",
+  "axios": "^0.26.1"
+},
+"overrides": {
+  "@stellar/stellar-sdk": {
+    "axios": "$axios"
+  }
+},
+"packageManager": "yarn@1.22.19"
+```
+
+Then, you need to override the adapter in your codebase:
+
+```typescript
+import { Horizon } from '@stellar/stellar-sdk';
+import fetchAdapter from '@vespaiach/axios-fetch-adapter';
+
+Horizon.AxiosClient.defaults.adapter = fetchAdapter as any;
+
+// then, the rest of your code...
+```
+
+All HTTP calls will use `fetch`, now, meaning it should work in the CloudFlare Worker environment.
+
+## Developing
+
+So you want to contribute to the library: welcome! Whether you're working on a fork or want to make an upstream request, the dev-test loop is pretty straightforward.
+
+1. Clone the repo:
+
+```shell
+git clone https://github.com/stellar/js-stellar-sdk.git
+```
+
+2. Install dependencies inside js-stellar-sdk folder:
+
+```shell
+cd js-stellar-sdk
+yarn
+```
+
+3. Install Node 18
+
+Because we support the oldest maintenance version of Node, please install and develop on Node 18 so you don't get surprised when your code works locally but breaks in CI.
+
+Here's how to install `nvm` if you haven't: https://github.com/creationix/nvm
+
+```shell
+nvm install 18
+
+# if you've never installed 18 before you'll want to re-install yarn
+npm install -g yarn
+```
+
+If you work on several projects that use different Node versions, you might it helpful to install this automatic version manager: https://github.com/wbyoung/avn
+
+4. Observe the project's code style
+
+While you're making changes, make sure to run the linter to catch any linting
+errors (in addition to making sure your text editor supports ESLint) and conform to the project's code style.
+
+```shell
+yarn fmt
+```
+
+### Building
+You can build the developer version (unoptimized, commented, with source maps, etc.) or the production bundles:
+
+```shell
+yarn build
+# or
+yarn build:prod
+```
+
+### Testing
 
 To run all tests:
 
@@ -229,13 +245,19 @@ To run a specific set of tests:
 ```shell
 yarn test:node
 yarn test:browser
+yarn test:integration
 ```
 
+In order to have a faster test loop, these suite-specific commands **do not** build the bundles first (unlike `yarn test`). If you make code changes, you will need to run `yarn build` (or a subset like `yarn build:node` corresponding to the test suite) before running the tests again to see your changes.
+
 To generate and check the documentation site:
 
 ```shell
 # install the `serve` command if you don't have it already
-npm install -g serve
+npm i -g serve
+
+# clone the base library for complete docs
+git clone https://github.com/stellar/js-stellar-base
 
 # generate the docs files
 yarn docs
@@ -246,28 +268,25 @@ cd jsdoc && serve .
 # you'll be able to browse the docs at http://localhost:5000
 ```
 
-## Documentation
+### Publishing
 
-Documentation for this repo lives in
-[Developers site](https://github.com/stellar/js-stellar-sdk/blob/master/docs/reference/readme.md).
+For information on how to contribute or publish new versions of this software to `npm`, please refer to our [contribution guide](https://github.com/stellar/js-stellar-sdk/blob/master/CONTRIBUTING.md).
 
-## Contributing
+## Miscellaneous
 
-For information on how to contribute, please refer to our
-[contribution guide](https://github.com/stellar/js-stellar-sdk/blob/master/CONTRIBUTING.md).
+### `stellar-sdk` vs `stellar-base`
 
-## Publishing to npm
+`stellar-sdk` is a high-level library that serves as client-side API for Horizon and Soroban RPC, while [`stellar-base](https://github.com/stellar/js-stellar-base) is lower-level library for creating Stellar primitive constructs via XDR helpers and wrappers.
 
-```
-npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease]
-```
+**Most people will want stellar-sdk instead of stellar-base.** You should only use stellar-base if you know what you're doing!
 
-A new version will be published to npm **and** Bower by GitHub actions.
+If you add `stellar-sdk` to a project, **do not add `stellar-base`!** Mismatching versions could cause weird, hard-to-find bugs. `stellar-sdk` automatically installs `stellar-base` and exposes all of its exports in case you need them.
 
-npm >= 2.13.0 required. Read more about
-[npm version](https://docs.npmjs.com/cli/version).
+> **Important!** The Node.js version of the `stellar-base` (`stellar-sdk` dependency) package uses the [`sodium-native`](https://www.npmjs.com/package/sodium-native) package as an [optional dependency](https://docs.npmjs.com/files/package.json#optionaldependencies). `sodium-native` is a low level binding to [libsodium](https://github.com/jedisct1/libsodium), (an implementation of [Ed25519](https://ed25519.cr.yp.to/) signatures).
+> If installation of `sodium-native` fails, or it is unavailable, `stellar-base` (and `stellar-sdk`) will fallback to using the [`tweetnacl`](https://www.npmjs.com/package/tweetnacl) package implementation. If you are using them in a browser, you can ignore this. However, for production backend deployments, you should be using `sodium-native`.
+> If `sodium-native` is successfully installed and working the `StellarSdk.FastSigning` variable will return `true`.
 
-## License
+### License
 
 js-stellar-sdk is licensed under an Apache-2.0 license. See the
 [LICENSE](https://github.com/stellar/js-stellar-sdk/blob/master/LICENSE) file