Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update README to flow better #907

Merged
merged 5 commits into from
Jan 10, 2024
Merged

Update README to flow better #907

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d99e9e8
WIP: Rearranging README docs
Shaptic Jan 9, 2024
0738de5
Update the README to flow better and incl. CFW stuff
Shaptic Jan 9, 2024
afb08b5
Fixups caught after the Markdown preview
Shaptic Jan 9, 2024
35bb3ba
Add code snippet around CFW usage
Shaptic Jan 10, 2024
28ee86d
Add advice around running tests + builds
Shaptic Jan 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
277 changes: 154 additions & 123 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@

<div align="center">
<img alt="Stellar" src="https://github.com/stellar/.github/raw/master/stellar-logo.png" width="558" />
<br/>
Expand All @@ -15,160 +16,87 @@

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.
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) and Soroban RPC (JSON-RPC-based).
- 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 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.

**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.
**Jump to:**

> **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`.
* [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)

## Quick start
## Installation

Using npm to include js-stellar-sdk in your own project:
Using npm or yarn to include `stellar-sdk` in your own project:

```shell
npm install --save @stellar/stellar-sdk
# or
yarn add @stellar/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>
````

## Install

### To use as a module in a Node.js project

1. Install it using npm:

```shell
npm install --save stellar-sdk
```

2. require/import it in your JavaScript:
Then, require or import it in your JavaScript code:

```js
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/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
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

# 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
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.

4. Observe the project's code style
| 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. |
|----|

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)

```shell
yarn fmt
```
## 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/) and Soroban JSON-RPC documentation [here](https://soroban.stellar.org/docs/reference/rpc).
* 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

Expand All @@ -192,7 +120,7 @@ module.exports = {

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:
Expand All @@ -207,16 +135,104 @@ At this point, the Stellar SDK will work, except that `StellarSdk.Keypair.random

```javascript
import * as Random from 'expo-random';
import StellarSdk from '@stellar/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:

Expand All @@ -229,13 +245,19 @@ To run a specific set of tests:
```shell
yarn test:node
yarn test:browser
yarn test:integration
Shaptic marked this conversation as resolved.
Show resolved Hide resolved
```

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
Expand All @@ -246,16 +268,25 @@ cd jsdoc && serve .
# you'll be able to browse the docs at http://localhost:5000
```

## Documentation
### Publishing

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).

Documentation for this repo lives in
[Developers site](https://github.com/stellar/js-stellar-sdk/blob/master/docs/reference/readme.md).
## Miscellaneous

## Contributing and Publishing
### `stellar-sdk` vs `stellar-base`

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).
`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.

**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 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
Expand Down
Loading