A library for working with the Diamante network, including communication with Aurora
npm install diamnet-sdkjs-diamnet-sdk is a JavaScript library for communicating with a
Diamante Aurora server.
It is used for building Diamante 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 Aurora endpoints (REST-based),
- facilities for building and signing transactions, for communicating with a
Diamante Aurora 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
- ...with React Native
- ...with Expo
- ...with CloudFlare Workers
- Developing: contribute to the project!
- Understanding diamnet-sdk vs. diamnet-base
- License
Using npm or yarn to include diamnet-sdk in your own project:
``shell`
npm install --save diamnet-sdkor
yarn add diamnet-sdk
Then, require or import it in your JavaScript code:
`js`
var DiamSdk = require("diamnet-sdk");
// or
import * as DiamSdk from "diamnet-sdk";
(Preferably, you would only import the pieces you need to enable tree-shaking and lower your final bundle sizes.)
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 :arrow_right: 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. |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
The usage documentation for this library lives in a handful of places:
- across the Diamante Developer Docs, which includes tutorials and examples,
- within this repository itself, and
You can also refer to:
- the documentation for the Aurora REST API (if using the Aurora module) and
1. Install yarn add --dev rn-nodeify
2. Add the following postinstall script:
`
yarn rn-nodeify --install url,events,https,http,util,stream,crypto,vm,buffer --hack --yarn
3. Uncomment require('crypto') on shim.jsreact-native link react-native-randombytes
4.
5. Create file
`
module.exports = {
resolver: {
extraNodeModules: require("node-libs-react-native"),
},
};
6. Add import "./shim"; to the top of index.js
7.
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.
#### Usage with Expo managed workflows
1. Install yarn add --dev rn-nodeify
2. Add the following postinstall script:
`
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)yarn add diamnet-sdk
4.
5.
At this point, the Diamante SDK will work, except that DiamSdk.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 { Keypair } from "diamnet-sdk";
const generateRandomKeypair = () => {
const randomBytes = Random.getRandomBytes(32);
return Keypair.fromRawEd25519Seed(Buffer.from(randomBytes));
};
`
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/diamcircle/js-diamnet-sdk.git
2. Install dependencies inside js-diamnet-sdk folder:
`shell`
cd js-diamnet-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 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
`$3
You can build the developer version (unoptimized, commented, with source maps, etc.) or the production bundles:
shell
yarn build
or
yarn build:prod
`$3
To run all tests:
shell
yarn test
`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
). 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 i -g serveclone the base library for complete docs
git clone https://github.com/diamcircle/js-diamnet-basegenerate the docs files
yarn docsget these files working in a browser
cd jsdoc && serve .you'll be able to browse the docs at http://localhost:5000
`$3
For information on how to contribute or publish new versions of this software to
, please refer to our contribution guide.Miscellaneous
$3
diamnet-sdk is a high-level library that serves as client-side API for Aurora and Soroban RPC, while diamnet-base is lower-level library for creating Diamante primitive constructs via XDR helpers and wrappers.Most people will want diamnet-sdk instead of diamnet-base. You should only use diamnet-base if you know what you're doing!
If you add diamnet-sdk to a project, do not add diamnet-base! Mismatching versions could cause weird, hard-to-find bugs. diamnet-sdk automatically installs diamnet-base and exposes all of its exports in case you need them.
> Important! The Node.js version of the diamnet-base (diamnet-sdk dependency) package uses the sodium-native package as an optional dependency. sodium-native is a low level binding to libsodium, (an implementation of Ed25519 signatures).
> If installation of sodium-native fails, or it is unavailable, diamnet-base (and diamnet-sdk) will fallback to using the 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 DiamSdk.FastSigning variable will return true.
js-diamnet-sdk is licensed under an Apache-2.0 license. See the
LICENSE file
for details.