Skip to content

Updates common structures #560

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

Closed
smk762 wants to merge 8 commits into from
Closed

Updates common structures #560

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
faa29ab
fix: correct NewAddressInfo balance structure in API documentation
Jul 30, 2025
1c24d1b
Merge pull request #559 from CharlVS/fix/get-new-address-balance-stru…
smk762 Jul 30, 2025
d2f0061
adds `NewAddressInfo` examples
smk762 Jul 30, 2025
170b513
remove unused/duplicated structure
smk762 Jul 30, 2025
5fa46e8
linting+
smk762 Jul 30, 2025
1985dd3
imports common structures updates
smk762 Jul 30, 2025
df03707
add structures for privkey method reponse
smk762 Aug 4, 2025
0e4659a
Merge pull request #562 from KomodoPlatform/kdf/import/common-structures
smk762 Aug 4, 2025
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
398 changes: 357 additions & 41 deletions filepathSlugs.json
View file
Open in desktop

Large diffs are not rendered by default.

17 changes: 17 additions & 0 deletions src/data/sidebar.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1135,6 +1135,23 @@
"titleLink": "/komodo-defi-framework/api/common_structures/",
"links": []
},
{
"title": "Structure Types",
"links": [
{
"title": "Enums",
"href": "/komodo-defi-framework/api/common_structures/enums/"
},
{
"title": "Error Types",
"href": "/komodo-defi-framework/api/common_structures/error_types/"
},
{
"title": "Rational Number Note",
"href": "/komodo-defi-framework/api/common_structures/rational_number_note/"
}
]
},
{
"title": "Activation Structures",
"titleLink": "/komodo-defi-framework/api/common_structures/activation/",
Expand Down
175 changes: 74 additions & 101 deletions src/pages/komodo-defi-framework/api/common_structures/activation/index.mdx
View file
Open in desktop

Large diffs are not rendered by default.

278 changes: 278 additions & 0 deletions src/pages/komodo-defi-framework/api/common_structures/enums/index.mdx
View file
Open in desktop

Large diffs are not rendered by default.

2,797 changes: 2,797 additions & 0 deletions src/pages/komodo-defi-framework/api/common_structures/error_types/index.mdx
View file
Open in desktop

Large diffs are not rendered by default.

291 changes: 153 additions & 138 deletions src/pages/komodo-defi-framework/api/common_structures/index.mdx
View file
Open in desktop

Large diffs are not rendered by default.

261 changes: 159 additions & 102 deletions src/pages/komodo-defi-framework/api/common_structures/lightning/index.mdx
View file
Open in desktop

Large diffs are not rendered by default.

201 changes: 120 additions & 81 deletions src/pages/komodo-defi-framework/api/common_structures/nfts/index.mdx
View file
Open in desktop

Large diffs are not rendered by default.

177 changes: 105 additions & 72 deletions src/pages/komodo-defi-framework/api/common_structures/orders/index.mdx
View file
Open in desktop

Large diffs are not rendered by default.

39 changes: 39 additions & 0 deletions ...ages/komodo-defi-framework/api/common_structures/rational_number_note/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
export const title = "Komodo DeFi Framework Method: Rational Number Type";
export const description = "The Komodo DeFi Framework API now offers the num-rational crate feature. This is used to represent order volumes and prices.";

# Rational Number Type

## rational\_number\_type {{label: 'rational_number_type', tag: 'overview'}}

The Komodo DeFi Framework API now offers the [num-rational crate](https://crates.io/crates/num-rational) feature. This is used to represent order volumes and prices.

Komodo highly recommends that the developer use the rational number type when calculating an order's price and volume. This avoids rounding and precision errors when calculating numbers, such as `1/3`, as these cannot be represented as a finite decimal.

The Komodo DeFi Framework API typically will return both the rational number type as well as the decimal representation, but the decimal representation should be considered only a convenience feature for readability.

The number can be represented in the following two JSON formats:

1. As a fraction object that contains a numerator and a denominator as numeric strings, as follows:

```json
{
"numer": "10000",
"denom": "3000"
}
```

2. As a unique format supplied by the `num-rational` crate:

```json
[
[1, [0, 1]],
[1, [1]]
]
```

In the above unique format, the first item `[1,[0,1]]` is the numerator and the second item `[1,[1]]` is the denominator.

The numerator and denominator are BigInteger numbers represented as a sign and a uint32 array (where numbers are 32-bit parts of big integer in little-endian order).

* `[1,[0,1]]` represents `+0000000000000000000000000000000010000000000000000000000000000000` = `4294967296`
* `[-1,[1,1]]` represents `-1000000000000000000000000000000010000000000000000000000000000000` = `-4294967297`
46 changes: 24 additions & 22 deletions src/pages/komodo-defi-framework/api/common_structures/swaps/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,18 @@
export const title = "Komodo DeFi SDK Common Structures: Swaps";
export const description = "Each active or completed trade from the Komodo DeFi SDK includes an unique identifier (UUID), a summary of the trade and detailed information relating to each swap event.";

# Swap Structures
# Swap Common Structures

## swaps\_common\_structures {{label : 'swaps_common_structures', tag : 'structures'}}

### SwapEvent

There are a variety if swap events which may occur during a trade. See [Maker Events](/komodo-defi-framework/api/common_structures/swaps/maker_events/) and [Taker Events](/komodo-defi-framework/api/common_structures/swaps/maker_events/) for more info.

| Parameter | Type | Description |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type | string | See [Maker Events](/komodo-defi-framework/api/common_structures/swaps/maker_events/) and [Taker Events](/komodo-defi-framework/api/common_structures/swaps/maker_events/) for more info. |
| data | varies | The data field may contain contextual information (e.g. txids) releated to a swap event. In some cases, it will be `null`. |
| Parameter | Type | Required | Description |
| --------- | ------ | :------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type | string | ✓ | See [Maker Events](/komodo-defi-framework/api/common_structures/swaps/maker_events/) and [Taker Events](/komodo-defi-framework/api/common_structures/swaps/maker_events/) for more info. |
| data | varies | ✓ | The data field may contain contextual information (e.g. txids) releated to a swap event. In some cases, it will be `null`. |

<CollapsibleSection expandedText="Hide Example" collapsedText="Show Example">
#### Example
Expand All @@ -30,10 +32,10 @@ There are a variety if swap events which may occur during a trade. See [Maker Ev

For each step of a trade, a `SwapEvent` will be created, alongside the timestamp of the event. See [Maker Events](/komodo-defi-framework/api/common_structures/swaps/maker_events/) and [Taker Events](/komodo-defi-framework/api/common_structures/swaps/maker_events/) for more info.

| Parameter | Type | Description |
| --------- | ------- | ---------------------------------------------------------------------------------------------- |
| timestamp | integer | Timestamp for the `SwapEvent` in UNIX format. |
| event | object | A standard [SwapEvent](/komodo-defi-framework/api/common_structures/swaps/#swap-event) object. |
| Parameter | Type | Required | Description |
| --------- | ------- | :------: | ---------------------------------------------------------------------------------------------- |
| timestamp | integer | ✓ | Timestamp for the `SwapEvent` in UNIX format. |
| event | object | ✓ | A standard [SwapEvent](/komodo-defi-framework/api/common_structures/swaps/#swap-event) object. |

<CollapsibleSection expandedText="Hide Example" collapsedText="Show Example">
#### Example
Expand All @@ -56,19 +58,19 @@ Each swap status will be nested under its associated UUID.
We should add a "maker" resonse example also. Unsure if `uuid` on maker side is swap or order uuid in response.
</DevComment>

| Parameter | Type | Description |
| --------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type | string | `Maker` or `Taker`. Indicates if the user created the order (maker), or matched with an existing order (taker). |
| uuid | string | A unique identifier for the swap. |
| events | list | A list of swap events. The structure of each event varies depending on its type, as detailed in the [SwapEvents](/komodo-defi-framework/api/common_structures/swaps/) section. |
| maker\_coin | string | The coin being sent by the maker and received by the taker. |
| taker\_coin | string | The coin being sent by the taker and received by the maker. |
| maker\_amount | numeric string | The amount of `maker_coin` being traded. |
| taker\_amount | numeric string | The amount of `taker_coin` being traded. |
| gui | string | An identifier for the GUI used to initiate the swap, as defined in your [MM2.json file](/komodo-defi-framework/setup/configure-mm2-json/). May be `null` if not defined. |
| mm\_version | string | The release version and/or commit hash of the Komodo DeFi SDK used to initiate the swap. |
| success\_events | list | A list of possible swap event types for a successful swap, for [makers](/komodo-defi-framework/api/common_structures/swaps/maker_events/#maker-success-events) and [takers](/komodo-defi-framework/api/common_structures/swaps/taker_events/#taker-success-events). |
| error\_events | list | A list of possible swap event types which may appear in a failed swap, for [makers](/komodo-defi-framework/api/common_structures/swaps/maker_events/#maker-error-events) and [takers](/komodo-defi-framework/api/common_structures/swaps/taker_events/#taker-error-events). |
| Parameter | Type | Required | Default | Description |
| --------------- | -------------- | :------: | :-----: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type | string | ✓ | `-` | `Maker` or `Taker`. Indicates if the user created the order (maker), or matched with an existing order (taker). |
| uuid | string | ✓ | `-` | A unique identifier for the swap. |
| events | list | ✓ | `-` | A list of swap events. The structure of each event varies depending on its type, as detailed in the [SwapEvents](/komodo-defi-framework/api/common_structures/swaps/) section. |
| maker\_coin | string | ✓ | `-` | The coin being sent by the maker and received by the taker. |
| taker\_coin | string | ✓ | `-` | The coin being sent by the taker and received by the maker. |
| maker\_amount | numeric string | ✓ | `-` | The amount of `maker_coin` being traded. |
| taker\_amount | numeric string | ✓ | `-` | The amount of `taker_coin` being traded. |
| gui | string | ✗ | `null` | An identifier for the GUI used to initiate the swap, as defined in your [MM2.json file](/komodo-defi-framework/setup/configure-mm2-json/). |
| mm\_version | string | ✓ | `-` | The release version and/or commit hash of the Komodo DeFi SDK used to initiate the swap. |
| success\_events | list | ✓ | `-` | A list of possible swap event types for a successful swap, for [makers](/komodo-defi-framework/api/common_structures/swaps/maker_events/#maker-success-events) and [takers](/komodo-defi-framework/api/common_structures/swaps/taker_events/#taker-success-events). |
| error\_events | list | ✓ | `-` | A list of possible swap event types which may appear in a failed swap, for [makers](/komodo-defi-framework/api/common_structures/swaps/maker_events/#maker-error-events) and [takers](/komodo-defi-framework/api/common_structures/swaps/taker_events/#taker-error-events). |

<CollapsibleSection expandedText="Hide Example" collapsedText="Show Example">
#### Example
Expand Down
Loading