ARCHIVE/xahau.js
1
0
Fork 0
mirror of https://github.com/Xahau/xahau.js.git synced 2025-11-04 04:55:48 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
xahau
xahau.js/CONTRIBUTING.md
Denis Angell 7916a14be2 refactor
2025-03-11 14:31:34 +01:00

13 KiB
Raw Permalink Blame History

Contributing

High Level Process to Contribute Code

  • You should open a PR against main and ensure that all CI passes.
  • Your changes should have unit and/or integration tests.
  • Your changes should pass the linter.
  • You should get a full code review from two of the maintainers.
  • Then you can merge your changes. (Which will then be included in the next release)

Set up your dev environment

Requirements

We use Node v18 for development - that is the version that our linters require. You must also use npm v7. You can check your npm version with:

npm -v

If your npm version is too old, use this command to update it:

npm -g i npm@7

Set up

  1. Clone the repository
  2. cd into the repository
  3. Install dependencies with npm install

Build

npm run build

Run the linter

npm install
npm run build
npm run lint

Running Tests

For integration and browser tests, we use a xahaud node in standalone mode to test xahau.js code against. To set this up, you can either configure and run xahaud locally, or set up the Docker container xahauci/xahaud by following these instructions. The latter will require you to install Docker.

Unit Tests

npm install
npm run build
npm test

Integration Tests

From the top-level xahau.js folder (one level above packages), run the following commands:

npm install
# sets up the xahaud standalone Docker container - you can skip this step if you already have it set up
docker run -p 6006:6006 --interactive -t --volume $PWD/.ci-config:/opt/xahau/etc/ --platform linux/amd64 xahauci/xahaud:2025.2.6 /opt/xahau/bin/xahaud -a --conf /opt/xahau/etc/xahaud.cfg
npm run build
npm run test:integration

Breaking down the command:

  • docker run -p 6006:6006 starts a Docker container with an open port for admin WebSocket requests.
  • --interactive allows you to interact with the container.
  • -t starts a terminal in the container for you to send commands to.
  • --volume $PWD/.ci-config:/config/ identifies the xahaud.cfg and validators.txt to import. It must be an absolute path, so we use $PWD instead of ./.
  • xahauci/xahaud is an image that is regularly updated with the latest xahaud releases
  • /opt/xahau/bin/xahaud -a --conf /opt/xahau/etc/xahaud.cfg starts xahaud in standalone mode

Browser Tests

There are two ways to run browser tests.

One is in the browser - run npm run build:browserTests and open test/localIntegrationRunner.html in your browser.

The other is in the command line (this is what we use for CI) -

This should be run from the xahau.js top level folder (one above the packages folder).

npm run build
# sets up the xahaud standalone Docker container - you can skip this step if you already have it set up
docker run -p 6006:6006 --interactive -t --volume $PWD/.ci-config:/opt/xahau/etc/ --platform linux/amd64 xahauci/xahaud:2025.2.6 /opt/xahau/bin/xahaud -a --conf /opt/xahau/etc/xahaud.cfg
npm run test:browser

High Level Architecture

This is a monorepo, which means that there are multiple packages in a single GitHub repository using Lerna.

The 4 packages currently here are:

  1. xahau.js - The client library for interacting with the ledger.
  2. xahau-binary-codec - A library for serializing and deserializing transactions for the ledger.
  3. xahau-keypairs - A library for generating and using cryptographic keypairs.
  4. xahau-address-codec - A library for encoding and decoding Xahau Ledger addresses and seeds.
  5. isomorphic - A collection of isomorphic implementations of crypto and utility functions.
  6. secret-numbers - Generate XRPL Accounts with a number-based secret: 8 chunks of 6 digits.

Each package has it's own README which dives deeper into what it's main purpose is, and the core functionality it offers. They also run tests independently as they were originally in separate repositories.

These are managed in a monorepo because often a change in a lower-level library will also require a change in xahau.js, and so it makes sense to be able to allow for modifications of all packages at once without coordinating versions across multiple repositories.

Let's dive a bit into how xahau.js is structured!

The File Structure

Within the xrpl package, each folder has a specific purpose:

Client - This contains logic for handling the websocket connection to xahaud servers. Models - These types model LedgerObjects, Requests/Methods, and Transactions in order to give type hints and nice errors for users. Sugar - This is where handy helper functions end up, like submit, autofill, and getXAHBalance amongst others. Utils - These are shared functions which are useful for conversions, or internal implementation details within the library. Wallet - This logic handles managing keys, addresses, and signing within xahau.js

Writing Tests for xahau.js

For every file in src, we try to have a corresponding file in test with unit tests.

The goal is to maintain above 80% code coverage, and generally any new feature or bug fix should be accompanied by unit tests, and integration tests if applicable.

For an example of a unit test, check out the autofill tests here.

If your code connects to the ledger (ex. Adding a new transaction type) it's handy to write integration tests to ensure that you can successfully interact with the ledger. Integration tests are generally run against a docker instance of xahaud which contains the latest updates. Since standalone mode allows us to manually close ledgers, this allows us to run integration tests at a much faster rate than if we had to wait 4-5 seconds per transaction for the ledger to validate the transaction. See above for how to start up the docker container to run integration tests.

All integration tests should be written in the test/integration folder, with new Requests and Transactions tests being in their respective folders.

For an example of how to write an integration test for xahau.js, you can look at the Payment integration test.

Generate reference docs

You can see the complete reference documentation at xahau.js docs. You can also generate them locally using typedoc:

npm run docgen

This updates docs/ at the top level, where GitHub Pages looks for the docs.

Update definitions.json

Use this repo to generate a new definitions.json file from the xahaud source code. Instructions are available in that README.

Adding and removing packages

xahau.js uses lerna and npm's workspaces features to manage a monorepo. Adding and removing packages requires a slightly different process than normal as a result.

Adding or removing development dependencies

xahau.js strives to use the same development dependencies in all packages. You may add and remove dev dependencies like normal:

### adding a new dependency
npm install --save-dev abbrev
### removing a dependency
npm uninstall --save-dev abbrev

Adding or removing runtime dependencies

You need to specify which package is changing using the -w flag:

### adding a new dependency to `xahau`
npm install abbrev -w xahau
### adding a new dependency to `xahau-keypairs`
npm install abbrev -w xahau-keypairs
### removing a dependency
npm uninstall abbrev -w xahau

Updating the Docker container for CI

In order to test the library, we need to enable the latest amendments in the docker container. This requires updating the /.ci-config/xahaud.cfg file with the hashes and names of new amendments.

In order to update the list, follow these steps from the top level of the library:

  1. Run node ./.ci-config/getNewAmendments.js
  2. If there are any new amendment hashes, add a comment to the end of /.ci-config/xahaud.cfg with the date
    • Ex. "# Added August 9th, 2023"
  3. For each hash printed out by the script, add the hash and name to the config file.
  4. Push your changes

Note: The same updated config can be used to update xahau-py's CI as well.

Updating definitions.json

This should almost always be done using the xrpl-codec-gen script - if the output needs manual intervention afterwards, consider updating the script instead.

  1. Clone / pull the latest changes from xahaud - Specifically the develop branch is usually the right one.
  2. Clone / pull the latest changes from xrpl-codec-gen
  3. From the xrpl-codec-gen tool, follow the steps in the README.md to generate a new definitions.json file.
  4. Replace the definitions.json file in the xahau-binary-codec with the newly generated file.
  5. Verify that the changes make sense by inspection before submitting, as there may be updates required for the xrpl-codec-gen tool depending on the latest amendments we're updating to match.

Release process + checklist

PR process

  • Your changes should be on a branch.
  • Your changes should have unit tests.
  • Lint the code with npm lint
  • Build your code with npm build
  • Run the unit tests with npm test
  • Get a full code review.
  • Merge your branch into main and push to github.
  • Ensure that all tests passed on the last CI that ran on main.

Release

  1. Checkout main (or your beta branch) and git pull.

  2. Create a new branch (git checkout -b <BRANCH_NAME>) to capture updates that take place during this process.

  3. Update HISTORY.md to reflect release changes.

    • Update the version number and release date, and ensure it lists the changes since the previous release.

  4. Run npm run docgen if the docs were modified in this release to update them (skip this step for a beta).

  5. Run npm run build to triple check the build still works

  6. Run npx lerna version --no-git-tag-version - This bumps the package versions.

    • For each changed package, pick what the new version should be. Lerna will bump the versions, commit version bumps to main, and create a new git tag for each published package.
    • If you do NOT want to update the package number, choose "Custom Version" and set the version to be the same as the existing version. Lerna will not publish any changes in this case.
    • If publishing a beta, make sure that the versions are all of the form a.b.c-beta.d, where a, b, and c are identical to the last normal release except for one, which has been incremented by 1.

  7. Run npm i to update the package-lock with the updated versions.

  8. Create a new PR from this branch into main and merge it (you can directly merge into the beta branch for a beta).

  9. Checkout main and git pull (you can skip this step for a beta since you already have the latest version of the beta branch).

  10. Actually publish the packages with one of the following:

    • Stable release: Run npx lerna publish from-package --yes
    • Beta release: Run npx lerna publish from-package --dist-tag beta --yes Notice this allows developers to install the package with npm add xahau@beta

  11. If requested, enter your npmjs.com OTP (one-time password) to complete publication.

    NOW YOU HAVE PUBLISHED! But you're not done; we have to notify people!

  12. Run git tag <tagname> -m <tagname>, where <tagname> is the new package and version (e.g. xahau@2.1.1), for each version released.

  13. Run git push --follow-tags, to push the tags to Github.

  14. On GitHub, click the "Releases" link on the right-hand side of the page.

  15. Repeat for each release:

    1. Click "Draft a new release"
    2. Click "Choose a tag", and choose a tag that you just created.
    3. Edit the name of the release to match the tag (IE <package>@<version>) and edit the description as you see fit.

  16. Send an email to xahau-announce.

  17. Lastly, send a similar message to the Xahau Discord in the javascript channel. The message should include:

    1. The version changes for xahau libraries
    2. A link to the more detailed changes
    3. Highlights of important changes

Mailing Lists

We have a low-traffic mailing list for announcements of new xahau.js releases. (About 1 email every couple of weeks)

If you're using the Xahau Ledger in production, you should run a xahaud server and subscribe to the xahau-server mailing list as well.