From e7e5a3a506797201aa795bb20dcfb4d351917ad1 Mon Sep 17 00:00:00 2001 From: Jackson Mills Date: Tue, 23 Jan 2024 15:44:44 -0800 Subject: [PATCH] Add a CONTRIBUTING.md to `ripple-binary-codec` (#2617) Add binary-codec-contributing doc --- packages/ripple-binary-codec/CONTRIBUTING.md | 29 ++++++++++++++++++++ packages/ripple-binary-codec/src/README.md | 4 ++- 2 files changed, 32 insertions(+), 1 deletion(-) create mode 100644 packages/ripple-binary-codec/CONTRIBUTING.md diff --git a/packages/ripple-binary-codec/CONTRIBUTING.md b/packages/ripple-binary-codec/CONTRIBUTING.md new file mode 100644 index 00000000..a712bfe5 --- /dev/null +++ b/packages/ripple-binary-codec/CONTRIBUTING.md @@ -0,0 +1,29 @@ +# Code structure + + - `enums` contains the logic for mapping types to their numerical id in rippled, which is used to serialize / deserialize later on. For more details, see its specific [README.md](src/enums/README.md) + - `serdes` contains the two main classes of this repo `BinarySerializer` and `BinaryParser` which actually do the serializing / deserializing. + - `types` defines how the library should convert between objects and binary data for each data type. These are then used by the `BinarySerializer` and `BinaryParser` to serialize / deserialize rippled data. + - At the top-level, we have helper functions for specific situations (like `encodeForMultisigning` in [index.ts](src/index.ts)). These functions are generally what are used by consumers of the library (with `BinarySerializer` and `BinaryParser` being used as the implementation under the hood) + +# Running tests +You can run tests for this repo with: +`npm i` to install necessary dependencies followed by either: +- `npm test` - Run unit tests in Node. +- `npm test:browser` - Run unit tests in the browser. + +## Adding tests +All tests should be added to the `test` folder, with long test data added to the [test/fixtures](test/fixtures) folder. + +For a good example unit test file, look at [test/hash.test.ts](test/hash.test.ts). + +If you add a new serializable type, please add a new file with tests that ensure it can be encoded / decoded, and that it throws any relevant errors. + +# Adding new serializable types +To add a new serializable type, first read through `enum`'s [README.md](src/enums/README.md) as it explains how to update `definitions.json` which ties `TransactionType`s and `Field`s to specific ids rippled understands. + +After that, if you need to add a new type of data to be serialized / deserialized (for example adding a bigger int than [uint-64.ts](src/types/uint-64.ts)) you can follow these steps: +1. Create a new class that extends `SerializedType` + - If your type is intended to be comparable to native values like `number`, you should extend `Comparable`. See [uint-64.ts](src/types/uint-64.ts) for an example of this. +2. Add your new subclass of `SerializableType` to `coreTypes` in [packages/ripple-binary-codec/src/types/index.ts](packages/ripple-binary-codec/src/types/index.ts) + - The `coreTypes` variable is used by `BinaryParser` and `BinarySerializer` to understand what possible types exist when reading / writing binary data. +3. Write a unit tests for this type that demonstrates it can properly serialize / deserialize and throw the proper errors (see [Adding Tests](#adding-tests)) diff --git a/packages/ripple-binary-codec/src/README.md b/packages/ripple-binary-codec/src/README.md index 5c5e62ad..16c040f0 100644 --- a/packages/ripple-binary-codec/src/README.md +++ b/packages/ripple-binary-codec/src/README.md @@ -1,3 +1,5 @@ # ripple-binary-codec -Serialize and deserialize transactions according to the XRP Ledger protocol. \ No newline at end of file +Serialize and deserialize transactions according to the XRP Ledger protocol. + +If you'd like to add a new transaction, data type, or generally modify this library, please read the [CONTRIBUTING.md](CONTRIBUTING.md)