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

xahau-patch

Browse Source
This commit is contained in:
Denis Angell
2025-03-12 13:34:24 +01:00
parent 92eb809397
commit 9544e1794e
958 changed files with 1686 additions and 169992 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
CONTRIBUTING.md
View File

@@ -47,7 +47,7 @@ npm run lint
## Running Tests
For integration and browser tests, we use a `rippled` node in standalone mode to test xrpl.js code against. To set this up, you can either configure and run `rippled` locally, or set up the Docker container `rippleci/rippled` by [following these instructions](#integration-tests). The latter will require you to [install Docker](https://docs.docker.com/get-docker/).
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](#integration-tests). The latter will require you to [install Docker](https://docs.docker.com/get-docker/).
### Unit Tests
@@ -59,12 +59,12 @@ npm test
### Integration Tests
From the top-level xrpl.js folder (one level above `packages`), run the following commands:
From the top-level xahau.js folder (one level above `packages`), run the following commands:
```bash
npm install
# sets up the rippled 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/ripple/etc/ --platform linux/amd64 rippleci/rippled:2.0.0-b4 /opt/ripple/bin/rippled -a --conf /opt/ripple/etc/rippled.cfg
# 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
```
@@ -73,9 +73,9 @@ 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 `rippled.cfg` and `validators.txt` to import. It must be an absolute path, so we use `$PWD` instead of `./`.
* `rippleci/rippled` is an image that is regularly updated with the latest `rippled` releases
* `/opt/ripple/bin/rippled -a --conf /opt/ripple/etc/rippled.cfg` starts `rippled` in standalone mode
* `--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
@@ -85,12 +85,12 @@ One is in the browser - run `npm run build:browserTests` and open `test/localInt
The other is in the command line (this is what we use for CI) -
This should be run from the `xrpl.js` top level folder (one above the `packages` folder).
This should be run from the `xahau.js` top level folder (one above the `packages` folder).
```bash
npm run build
# sets up the rippled 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/ripple/etc/ --platform linux/amd64 rippleci/rippled:2.2.0-b3 /opt/ripple/bin/rippled -a --conf /opt/ripple/etc/rippled.cfg
# 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
```
@@ -100,47 +100,47 @@ This is a monorepo, which means that there are multiple packages in a single Git
The 4 packages currently here are:
1. xrpl.js - The client library for interacting with the ledger.
2. ripple-binary-codec - A library for serializing and deserializing transactions for the ledger.
3. ripple-keypairs - A library for generating and using cryptographic keypairs.
4. ripple-address-codec - A library for encoding and decoding XRP Ledger addresses and seeds.
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 xrpl.js, and so it makes sense to be able to allow for modifications of all packages at once without coordinating versions across multiple 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 xrpl.js is structured!
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 rippled servers.
**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 `getXRPBalance` amongst others.
**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 xrpl.js
**Wallet** - This logic handles managing keys, addresses, and signing within xahau.js
### Writing Tests for xrpl.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](./packages/xrpl/test/client/autofill.ts).
For an example of a unit test, check out the [autofill tests here](./packages/xahau/test/client/autofill.ts).
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 rippled 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](#running-tests) for how to start up the docker container to run integration tests.
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](#running-tests) 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 `xrpl.js`, you can look at the [Payment integration test](./packages/xrpl/test/integration/transactions/payment.ts).
For an example of how to write an integration test for `xahau.js`, you can look at the [Payment integration test](./packages/xahau/test/integration/transactions/payment.ts).
## Generate reference docs
You can see the complete reference documentation at [`xrpl.js` docs](https://js.xrpl.org). You can also generate them locally using `typedoc`:
You can see the complete reference documentation at [`xahau.js` docs](https://js.xrpl.org). You can also generate them locally using `typedoc`:
```bash
npm run docgen
@@ -150,17 +150,17 @@ This updates `docs/` at the top level, where GitHub Pages looks for the docs.
## Update `definitions.json`
Use [this repo](https://github.com/RichardAH/xrpl-codec-gen) to generate a new `definitions.json` file from the rippled source code. Instructions are available in that README.
Use [this repo](https://github.com/RichardAH/xrpl-codec-gen) to generate a new `definitions.json` file from the xahaud source code. Instructions are available in that README.
## Adding and removing packages
`xrpl.js` uses `lerna` and `npm`'s workspaces features to manage a monorepo.
`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
`xrpl.js` strives to use the same development dependencies in all packages.
`xahau.js` strives to use the same development dependencies in all packages.
You may add and remove dev dependencies like normal:
```bash
@@ -175,38 +175,38 @@ npm uninstall --save-dev abbrev
You need to specify which package is changing using the `-w` flag:
```bash
### adding a new dependency to `xrpl`
npm install abbrev -w xrpl
### adding a new dependency to `ripple-keypairs`
npm install abbrev -w ripple-keypairs
### 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 xrpl
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/rippled.cfg` file with the hashes and names of new amendments.
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/rippled.cfg` with the date
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.
- Ex. `B2A4DB846F0891BF2C76AB2F2ACC8F5B4EC64437135C6E56F3F859DE5FFD5856 ExpandedSignerList`
- You can look up the name by searching for the hash on https://xrpl.org/known-amendments.html
4. Push your changes
Note: The same updated config can be used to update xrpl-py's CI as well.
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`](https://github.com/RichardAH/xrpl-codec-gen) script - if the output needs manual intervention afterwards, consider updating the script instead.
1. Clone / pull the latest changes from [rippled](https://github.com/XRPLF/rippled) - Specifically the `develop` branch is usually the right one.
1. Clone / pull the latest changes from [xahaud](https://github.com/XRPLF/xahaud) - Specifically the `develop` branch is usually the right one.
2. Clone / pull the latest changes from [`xrpl-codec-gen`](https://github.com/RichardAH/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 `ripple-binary-codec` with the newly generated 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.
@@ -246,13 +246,13 @@ This should almost always be done using the [`xrpl-codec-gen`](https://github.co
- 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 xrpl@beta`
Notice this allows developers to install the package with `npm add xahau@beta`
1. If requested, enter your [npmjs.com](https://npmjs.com) OTP (one-time password) to complete publication.
NOW YOU HAVE PUBLISHED! But you're not done; we have to notify people!
1. Run `git tag <tagname> -m <tagname>`, where `<tagname>` is the new package and version (e.g. `xrpl@2.1.1`), for each version released.
1. Run `git tag <tagname> -m <tagname>`, where `<tagname>` is the new package and version (e.g. `xahau@2.1.1`), for each version released.
1. Run `git push --follow-tags`, to push the tags to Github.
1. On GitHub, click the "Releases" link on the right-hand side of the page.
@@ -262,19 +262,19 @@ This should almost always be done using the [`xrpl-codec-gen`](https://github.co
1. Click "Choose a tag", and choose a tag that you just created.
1. Edit the name of the release to match the tag (IE \<package\>@\<version\>) and edit the description as you see fit.
1. Send an email to [xrpl-announce](https://groups.google.com/g/xrpl-announce).
1. Lastly, send a similar message to the XRPL Discord in the [`javascript` channel](https://discord.com/channels/886050993802985492/886053111179915295). The message should include:
1. The version changes for xrpl libraries
1. Send an email to [xahau-announce](https://groups.google.com/g/xahau-announce).
1. Lastly, send a similar message to the Xahau Discord in the [`javascript` channel](https://discord.com/channels/1085202760548499486/1085203623111295068). The message should include:
1. The version changes for xahau libraries
1. A link to the more detailed changes
1. Highlights of important changes
## Mailing Lists
We have a low-traffic mailing list for announcements of new `xrpl.js` releases. (About 1 email every couple of weeks)
We have a low-traffic mailing list for announcements of new `xahau.js` releases. (About 1 email every couple of weeks)
- [Subscribe to xrpl-announce](https://groups.google.com/g/xrpl-announce)
- [Subscribe to xahau-announce](https://groups.google.com/g/xahau-announce)
If you're using the XRP Ledger in production, you should run a [rippled server](https://github.com/ripple/rippled) and subscribe to the ripple-server mailing list as well.
If you're using the Xahau Ledger in production, you should run a [xahaud server](https://github.com/xahau/xahaud) and subscribe to the xahau-server mailing list as well.
- [Subscribe to ripple-server](https://groups.google.com/g/ripple-server)
- [Subscribe to xahau-server](https://groups.google.com/g/xahau-server)