js-stellar-sdk is a JavaScript library for communicating with a Stellar Horizon server and Soroban 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 (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.
Jump to:
- Installation: details on hitting the ground running
- Usage: links to documentation and a variety of workarounds for non-traditional JavaScript environments
- Developing: contribute to the project!
- Understanding
stellar-sdk
vs.stellar-base
- License
Using npm or yarn to include stellar-sdk
in your own project:
npm install --save @stellar/stellar-sdk
# or
yarn add @stellar/stellar-sdk
Then, require or import it in your JavaScript code:
var StellarSdk = require('@stellar/stellar-sdk');
// or
import * as StellarSdk from '@stellar/stellar-sdk';
(Preferably, you would only import the pieces you need to enable tree-shaking and lower your final bundle sizes.)
You can use a CDN:
<script src="https://cdnjs.cloudflare.com/ajax/libs/stellar-sdk/{version}/stellar-sdk.js"></script>
Note that this method relies on using a third party to host the JS library. This may not be entirely secure. You can self-host it via Bower:
bower install @stellar/stellar-sdk
and include it in the browser:
<script src="./bower_components/stellar-sdk/stellar-sdk.js"></script>
<script>
console.log(StellarSdk);
</script>
If you don't want to use or install Bower, you can copy the packaged JS files from the Bower repo, or just build the package yourself locally (see Developing ➡️ Building) and copy the bundle.
Always make sure that you are using the latest version number. They can be found on the releases page in GitHub. |
---|
You can configure whether or not to build the browser bundle with the axios dependency. In order to turn off the axios dependency, set the USE_AXIOS environment variable to false. You can also turn off the eventsource dependency by setting USE_EVENTSOURCE to false.
npm run build:browser:no-axios
This will create stellar-sdk-no-axios.js
in dist/
.
npm run build:browser:no-eventsource
This will create stellar-sdk-no-eventsource.js
in dist/
.
npm run build:browser:minimal
This will create stellar-sdk-minimal.js
in dist/
.
The usage documentation for this library lives in a handful of places:
- across the Stellar Developer Docs, which includes tutorials and examples,
- within this repository itself, and
- on the generated API doc site.
You can also refer to:
- the documentation for the Horizon REST API (if using the
Horizon
module) and - the documentation for Soroban RPC's API (if using the
rpc
module)
- Install
yarn add --dev rn-nodeify
- Add the following postinstall script:
yarn rn-nodeify --install url,events,https,http,util,stream,crypto,vm,buffer --hack --yarn
- Uncomment
require('crypto')
on shim.js react-native link react-native-randombytes
- Create file
rn-cli.config.js
module.exports = {
resolver: {
extraNodeModules: require("node-libs-react-native"),
},
};
- Add
import "./shim";
to the top ofindex.js
yarn add @stellar/stellar-sdk
There is also a sample that you can follow.
Note: Only the V8 compiler (on Android) and JSC (on iOS) have proper support for Buffer
and Uint8Array
as is needed by this library. Otherwise, you may see bizarre errors when doing XDR encoding/decoding such as source not specified
.
- Install
yarn add --dev rn-nodeify
- Add the following postinstall script:
yarn rn-nodeify --install process,url,events,https,http,util,stream,crypto,vm,buffer --hack --yarn
- Add
import "./shim";
to your app's entry point (by default./App.js
) yarn add @stellar/stellar-sdk
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:
import * as Random from 'expo-random';
import { Keypair } from '@stellar/stellar-sdk';
const generateRandomKeypair = () => {
const randomBytes = Random.getRandomBytes(32);
return Keypair.fromRawEd25519Seed(Buffer.from(randomBytes));
};
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
is an attempt to resolve these issues.
It requires the following additional tweaks to your project:
- the
axios-fetch-adapter
lets you useaxios
withfetch
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:
"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:
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.
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.
- Clone the repo:
git clone https://github.com/stellar/js-stellar-sdk.git
- Install dependencies inside js-stellar-sdk folder:
cd js-stellar-sdk
yarn
- 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
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
- 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.
yarn fmt
You can build the developer version (unoptimized, commented, with source maps, etc.) or the production bundles:
yarn build
# or
yarn build:prod
To run all tests:
yarn test
To run a specific set of tests:
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:
# install the `serve` command if you don't have it already
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
# get these files working in a browser
cd jsdoc && serve .
# you'll be able to browse the docs at http://localhost:5000
For information on how to contribute or publish new versions of this software to npm
, please refer to our contribution guide.
stellar-sdk
is a high-level library that serves as client-side API for Horizon and Soroban RPC, while `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
! 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.
Important! The Node.js version of the
stellar-base
(stellar-sdk
dependency) package uses thesodium-native
package as an optional dependency.sodium-native
is a low level binding to libsodium, (an implementation of Ed25519 signatures). If installation ofsodium-native
fails, or it is unavailable,stellar-base
(andstellar-sdk
) will fallback to using thetweetnacl
package implementation. If you are using them in a browser, you can ignore this. However, for production backend deployments, you should be usingsodium-native
. Ifsodium-native
is successfully installed and working theStellarSdk.FastSigning
variable will returntrue
.
js-stellar-sdk is licensed under an Apache-2.0 license. See the LICENSE file for details.