diff --git a/docs/evernode-js-api.md b/docs/evernode-js-api.md index b92bdf3..d5cd810 100644 --- a/docs/evernode-js-api.md +++ b/docs/evernode-js-api.md @@ -61,6 +61,26 @@ It extends the BaseEvernodeClient.

+## Constants + +
+
GovernorEvents
+

Following governor-specific events can be subscribed from Evernode client instances.

+
+
HeartbeatEvents
+

Following heartbeat-specific events can be subscribed from Evernode client instances.

+
+
RegistryEvents
+

Following registry-specific events can be subscribed from Evernode client instances.

+
+
HostEvents
+

Following host-specific events can be subscribed from Evernode client instances.

+
+
TenantEvents
+

Following tenant-specific events can be subscribed from Evernode client instances.

+
+
+ ## BaseEvernodeClient @@ -157,12 +177,20 @@ Connects the client to xrpl server and do the config loading and subscriptions. **Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) **Returns**: Boolean value `true` if the connection is successful. +**Example** +```js +const status = await client.connect(); +``` ### baseEvernodeClient.disconnect() Disconnects the client to xrpl server and do the un-subscriptions. 'unsubscribe' is called inside this. **Kind**: instance method of [BaseEvernodeClient](#BaseEvernodeClient) +**Example** +```js +await client.disconnect(); +``` ### baseEvernodeClient.subscribe() @@ -588,6 +616,10 @@ Connects the client to xrpl server and do the config loading and subscriptions. **Kind**: instance method of [FoundationClient](#FoundationClient) **Overrides**: [connect](#BaseEvernodeClient+connect) **Returns**: Boolean value `true` if the connection is successful. +**Example** +```js +const status = await client.connect(); +``` ### foundationClient.disconnect() @@ -595,6 +627,10 @@ Disconnects the client to xrpl server and do the un-subscriptions. 'unsubscribe' **Kind**: instance method of [FoundationClient](#FoundationClient) **Overrides**: [disconnect](#BaseEvernodeClient+disconnect) +**Example** +```js +await client.disconnect(); +``` ### foundationClient.subscribe() @@ -838,6 +874,7 @@ It interacts with the XRP Ledger using the governor address and listens for spec **Extends**: [BaseEvernodeClient](#BaseEvernodeClient) * [GovernorClient](#GovernorClient) ⇐ [BaseEvernodeClient](#BaseEvernodeClient) + * [new GovernorClient([options])](#new_GovernorClient_new) * [.on(event, handler)](#BaseEvernodeClient+on) * [.once(event, handler)](#BaseEvernodeClient+once) * [.off(event, handler)](#BaseEvernodeClient+off) @@ -865,6 +902,23 @@ It interacts with the XRP Ledger using the governor address and listens for spec * [.getReputationContractInfoByAddress(hostsAddress, moment)](#BaseEvernodeClient+getReputationContractInfoByAddress) ⇒ * [.getReputationInfoByAddress(hostsAddress)](#BaseEvernodeClient+getReputationInfoByAddress) ⇒ + + +### new GovernorClient([options]) +Creates an instance of GovernorClient. + + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| [options] | Object | {} | A JSON object of options for initializing the GovernorClient. | +| [options.governorAddress] | string | | (Optional) The Governor Hook Account Xahau address. If not provided, the address from the 'Defaults' configuration will be used. | + +**Example** +```js +const governorClient = new GovernorClient({ + governorAddress: "rGVHr1PrfL93UAjyw3DWZoi9adz2sLp2yL" +}); +``` ### governorClient.on(event, handler) @@ -912,6 +966,10 @@ Connects the client to xrpl server and do the config loading and subscriptions. **Kind**: instance method of [GovernorClient](#GovernorClient) **Overrides**: [connect](#BaseEvernodeClient+connect) **Returns**: Boolean value `true` if the connection is successful. +**Example** +```js +const status = await client.connect(); +``` ### governorClient.disconnect() @@ -919,6 +977,10 @@ Disconnects the client to xrpl server and do the un-subscriptions. 'unsubscribe' **Kind**: instance method of [GovernorClient](#GovernorClient) **Overrides**: [disconnect](#BaseEvernodeClient+disconnect) +**Example** +```js +await client.disconnect(); +``` ### governorClient.subscribe() @@ -1162,6 +1224,7 @@ It interacts with the XRP Ledger using the heartbeat address and listens for spe **Extends**: [BaseEvernodeClient](#BaseEvernodeClient) * [HeartbeatClient](#HeartbeatClient) ⇐ [BaseEvernodeClient](#BaseEvernodeClient) + * [new HeartbeatClient([options])](#new_HeartbeatClient_new) * [.on(event, handler)](#BaseEvernodeClient+on) * [.once(event, handler)](#BaseEvernodeClient+once) * [.off(event, handler)](#BaseEvernodeClient+off) @@ -1189,6 +1252,25 @@ It interacts with the XRP Ledger using the heartbeat address and listens for spe * [.getReputationContractInfoByAddress(hostsAddress, moment)](#BaseEvernodeClient+getReputationContractInfoByAddress) ⇒ * [.getReputationInfoByAddress(hostsAddress)](#BaseEvernodeClient+getReputationInfoByAddress) ⇒ + + +### new HeartbeatClient([options]) +Creates an instance of HeartbeatClient. + + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| [options] | Object | {} | A JSON object of options for initializing the HeartbeatClient. | +| options.heartbeatAddress | string | | The Heartbeat Hook Account Xahau address. | +| [options.rippledServer] | string | | (Optional) The Rippled server URL. | + +**Example** +```js +const heartbeatClient = new HeartbeatClient({ + heartbeatAddress: 'raPSFU999HcwpyRojdNh2i96T22gY9fgxL', + rippledServer: 'wss://hooks-testnet-v3.xrpl-labs.com' +}); +``` ### heartbeatClient.on(event, handler) @@ -1236,6 +1318,10 @@ Connects the client to xrpl server and do the config loading and subscriptions. **Kind**: instance method of [HeartbeatClient](#HeartbeatClient) **Overrides**: [connect](#BaseEvernodeClient+connect) **Returns**: Boolean value `true` if the connection is successful. +**Example** +```js +const status = await client.connect(); +``` ### heartbeatClient.disconnect() @@ -1243,6 +1329,10 @@ Disconnects the client to xrpl server and do the un-subscriptions. 'unsubscribe' **Kind**: instance method of [HeartbeatClient](#HeartbeatClient) **Overrides**: [disconnect](#BaseEvernodeClient+disconnect) +**Example** +```js +await client.disconnect(); +``` ### heartbeatClient.subscribe() @@ -1482,6 +1572,16 @@ Get reputation info of given host. A factory class for creating different types of hook clients based on the provided hook type. **Kind**: global class +**Summary**: In Evernode, there are three distinct types of hooks: + +- Governor Hook +- Registry Hook +- Heartbeat Hook +- Reputation Hook + +Each of these hooks is associated with a separate Xahau account. Therefore, in various scenarios, it becomes necessary to create client instances to engage with these hooks. +This section aims to enhance your comprehension of the available hook clients in Evernode. It will provide you with detailed specifications and guidance on how to utilize them effectively within Evernode. +The Hook Client Factory provides a common interface for creating hook clients. Developers can instantiate hook clients with minimal effort. ### HookClientFactory.create(hookType, [options]) ⇒ Promise.<(Object\|null)> @@ -1499,6 +1599,14 @@ Creates a hook client from given type. | hookType | string | | Type of the Required Hook. (Supported Hook types 'GOVERNOR', 'REGISTRY', 'HEARTBEAT' and 'REPUTATION') | | [options] | Object | {} | Optional configuration for the hook client. | +**Example** +```js +Defaults.set({governorAddress: "rGVHr1PrfL93UAjyw3DWZoi9adz2sLp2yL"}); +const governorClient = await HookClientFactory.create(HookTypes.governor); +const registryClient = await HookClientFactory.create(HookTypes.registry); +const heartbeatClient = await HookClientFactory.create(HookTypes.heartbeat); +const reputationClient = await HookClientFactory.create(HookTypes.reputation); +``` ## RegistryClient ⇐ [BaseEvernodeClient](#BaseEvernodeClient) @@ -1509,6 +1617,7 @@ It interacts with the XRP Ledger using the registry address and listens for spec **Extends**: [BaseEvernodeClient](#BaseEvernodeClient) * [RegistryClient](#RegistryClient) ⇐ [BaseEvernodeClient](#BaseEvernodeClient) + * [new RegistryClient([options])](#new_RegistryClient_new) * [.getActiveHostsFromLedger()](#RegistryClient+getActiveHostsFromLedger) ⇒ Promise.<Array> * [.on(event, handler)](#BaseEvernodeClient+on) * [.once(event, handler)](#BaseEvernodeClient+once) @@ -1537,6 +1646,25 @@ It interacts with the XRP Ledger using the registry address and listens for spec * [.getReputationContractInfoByAddress(hostsAddress, moment)](#BaseEvernodeClient+getReputationContractInfoByAddress) ⇒ * [.getReputationInfoByAddress(hostsAddress)](#BaseEvernodeClient+getReputationInfoByAddress) ⇒ + + +### new RegistryClient([options]) +Creates an instance of RegistryClient. + + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| [options] | Object | {} | A JSON object of options for initializing the RegistryClient. | +| options.registryAddress | string | | The Registry Hook Account Xahau address. | +| [options.rippledServer] | string | | (Optional) The Rippled server URL. | + +**Example** +```js +const registryClient = new RegistryClient({ + registryAddress: 'rQUhXd7sopuga3taru3jfvc1BgVbscrb1X', + rippledServer: 'wss://hooks-testnet-v3.xrpl-labs.com' +}); +``` ### registryClient.getActiveHostsFromLedger() ⇒ Promise.<Array> @@ -1591,6 +1719,10 @@ Connects the client to xrpl server and do the config loading and subscriptions. **Kind**: instance method of [RegistryClient](#RegistryClient) **Overrides**: [connect](#BaseEvernodeClient+connect) **Returns**: Boolean value `true` if the connection is successful. +**Example** +```js +const status = await client.connect(); +``` ### registryClient.disconnect() @@ -1598,6 +1730,10 @@ Disconnects the client to xrpl server and do the un-subscriptions. 'unsubscribe' **Kind**: instance method of [RegistryClient](#RegistryClient) **Overrides**: [disconnect](#BaseEvernodeClient+disconnect) +**Example** +```js +await client.disconnect(); +``` ### registryClient.subscribe() @@ -2370,6 +2506,10 @@ Connects the client to xrpl server and do the config loading and subscriptions. **Kind**: instance method of [HostClient](#HostClient) **Overrides**: [connect](#BaseEvernodeClient+connect) **Returns**: Boolean value `true` if the connection is successful. +**Example** +```js +const status = await client.connect(); +``` ### hostClient.disconnect() @@ -2377,6 +2517,10 @@ Disconnects the client to xrpl server and do the un-subscriptions. 'unsubscribe' **Kind**: instance method of [HostClient](#HostClient) **Overrides**: [disconnect](#BaseEvernodeClient+disconnect) +**Example** +```js +await client.disconnect(); +``` ### hostClient.subscribe() @@ -2626,7 +2770,7 @@ It extends the BaseEvernodeClient. * [.acquireLeaseSubmit(hostAddress, requirement, options)](#TenantClient+acquireLeaseSubmit) ⇒ * [.prepareAcquireLeaseTransaction(hostAddress, requirement, options)](#TenantClient+prepareAcquireLeaseTransaction) ⇒ * [.watchAcquireResponse(tx, options)](#TenantClient+watchAcquireResponse) ⇒ - * [.acquireLease(hostAddress, requirement, options)](#TenantClient+acquireLease) ⇒ + * [.acquireLease(hostAddress, requirement, [options])](#TenantClient+acquireLease) ⇒ Promise.<Object> \| Object \| string \| string \| string \| string \| number \| Array.<Object> \| string \| number \| string \| Object \| string \| string \| string \| string \| string \| string \| string * [.extendLeaseSubmit(hostAddress, amount, tokenID, options)](#TenantClient+extendLeaseSubmit) ⇒ * [.prepareExtendLeaseTransaction(hostAddress, amount, tokenID, options)](#TenantClient+prepareExtendLeaseTransaction) ⇒ * [.watchExtendResponse(tx, options)](#TenantClient+watchExtendResponse) ⇒ @@ -2667,10 +2811,19 @@ Creates an instance of TenantClient. | Param | Type | Default | Description | | --- | --- | --- | --- | -| xrpAddress | string | | The XRP address to associate with this client. | -| xrpSecret | string | | The secret (private key) associated with the XRP address. | -| [options] | Object | {} | Additional configuration options for the TenantClient. | - +| xrpAddress | string | | Xahau wallet address of the tenant. | +| xrpSecret | string | | Secret key of the tenant's Xahau wallet. | +| [options] | Object | {} | (Optional) A JSON object of options that can include the following properties. | +| [options.governorAddress] | string | | (Optional) The Governor Hook Account Xahau address. | +| [options.rippledServer] | string | | (Optional) The Rippled server URL. | + +**Example** +```js +const client = new TenantClient("rKfHBc8e1VemZPLZoPXB7HjSKU2QjkRfP", "sszyYJ79AdUUF6dR7QfD9ARWfVuz3", { + governorAddress: "rGVHr1PrfL93UAjyw3DWZoi9adz2sLp2yL", + rippledServer: "wss://hooks-testnet-v3.xrpl-labs.com" +}); +``` ### tenantClient.prepareAccount([options]) @@ -2741,18 +2894,58 @@ Watch for the acquire-success response after the acquire request is made. -### tenantClient.acquireLease(hostAddress, requirement, options) ⇒ -Acquire an instance from a host +### tenantClient.acquireLease(hostAddress, requirement, [options]) ⇒ Promise.<Object> \| Object \| string \| string \| string \| string \| number \| Array.<Object> \| string \| number \| string \| Object \| string \| string \| string \| string \| string \| string \| string +Acquires an available instance on a specified host. **Kind**: instance method of [TenantClient](#TenantClient) -**Returns**: An object including transaction details,instance info, and acquireReference Id. +**Returns**: Promise.<Object> - Resolves with an object containing the transaction details and instance details.Object - transaction - Information about the transaction.string - transaction.Account - The address of the account initiating the transaction.string - transaction.Amount - The amount of currency transferred.string - transaction.Destination - The tenant's account address.string - transaction.Fee - The fee paid for the transaction, in EVR drops.number - transaction.LastLedgerSequence - The latest ledger sequence for the transaction.Array.<Object> - transaction.Memos - Array of memo objects.string - transaction.hash - The SHA-512 hash of the transaction.number - transaction.ledger_index - The ledger index containing the transaction.string - transaction.DeliveredAmount - The actual amount delivered to the destination.Object - instance - Information about the acquired instance.string - instance.name - The unique identifier (URITokenID) of the instance.string - instance.pubkey - The public key of the instance.string - instance.contract_id - The unique contract identifier.string - instance.peer_port - The port used for peer communication.string - instance.user_port - The port used for user communication.string - instance.domain - The public domain of the host server.string - acquireRefId - The reference ID for the acquisition. +**Throws**: -| Param | Type | Description | -| --- | --- | --- | -| hostAddress | string | XRPL address of the host to acquire the lease. | -| requirement | object | The instance requirements and configuration. | -| options | object | [Optional] Options for the XRPL transaction. | +- Error Throws an error if the acquisition fails. +- Object error - The error object with details about the failure. +- string error.error - The error code ('ACQUIRE_ERR'). +- string error.reason - The reason for the acquisition failure. +- Object error.transaction - The transaction details associated with the failed acquisition. +- string error.transaction.Account - The tenant's account address. +- Object error.transaction.Amount - The refund details. +- string error.transaction.Amount.currency - The currency type (e.g., 'EVR'). +- string error.transaction.Amount.issuer - The issuer of the currency. +- string error.transaction.Amount.value - The value of the refunded amount. +- string error.transaction.Destination - The tenant's account address. +- string error.transaction.Fee - The transaction fee. +- Array.<Object> error.transaction.HookParameters - Contains event name and event data. +- string error.transaction.HookParameters[].name - The event name (in hex format). +- string error.transaction.HookParameters[].value - The event data (in hex format). +- string error.acquireRefId - The reference ID for the failed acquisition request. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| hostAddress | string | | The wallet address of the host where the HotPocket instance will be created. | +| requirement | Object | | The details necessary for creating the instance. | +| requirement.owner_pubkey | string | | The public key of the tenant. | +| requirement.contract_id | string | | The unique contract identifier. | +| requirement.image | string | | The image used to create the HotPocket instance. | +| requirement.config | Object | | Configuration object for the instance. | +| [options] | Object | {} | Optional configurations for the transaction. | +| [options.timeout] | number | 60000 | Timeout for the transaction in milliseconds. | +| [options.leaseOfferIndex] | string | | The index of the preferred lease offer from the host. | +| [options.transactionOptions] | Object | | Options for the URITokenBuy transaction as defined in the Xahau documentation. | + +**Example** +```js +const result = await tenant.acquireLease( + "rnET2YR19WDP4vB8XtDhcF2J4afqMM6xim", + { + owner_pubkey: "ed5cb83404120ac759609819591ef839b7d222c84f1f08b3012f490586159d2b50", + contract_id: "dc411912-bcdd-4f73-af43-32ec45844b9a", + image: "evernodedev/sashimono:hp.latest-ubt.20.04-njs.16", + config: {} + }, + { timeout: 10000 } +); +console.log("Tenant received instance:", result); +``` ### tenantClient.extendLeaseSubmit(hostAddress, amount, tokenID, options) ⇒ @@ -2869,6 +3062,10 @@ Connects the client to xrpl server and do the config loading and subscriptions. **Kind**: instance method of [TenantClient](#TenantClient) **Overrides**: [connect](#BaseEvernodeClient+connect) **Returns**: Boolean value `true` if the connection is successful. +**Example** +```js +const status = await client.connect(); +``` ### tenantClient.disconnect() @@ -2876,6 +3073,10 @@ Disconnects the client to xrpl server and do the un-subscriptions. 'unsubscribe' **Kind**: instance method of [TenantClient](#TenantClient) **Overrides**: [disconnect](#BaseEvernodeClient+disconnect) +**Example** +```js +await client.disconnect(); +``` ### tenantClient.subscribe() @@ -3119,7 +3320,7 @@ Defaults class is responsible for retrieving and overriding the default Evernode * [Defaults](#Defaults) * [.values](#Defaults.values) ⇒ * [.useNetwork(network)](#Defaults.useNetwork) - * [.set(newDefaults)](#Defaults.set) + * [.set(newDefaults)](#Defaults.set) ⇒ void @@ -3128,6 +3329,10 @@ Read Evernode default configs. **Kind**: static property of [Defaults](#Defaults) **Returns**: The Object of Evernode configs +**Example** +```js +const defaults = Defaults.values; +``` ### Defaults.useNetwork(network) @@ -3141,7 +3346,7 @@ Load defaults from the public definitions json. -### Defaults.set(newDefaults) +### Defaults.set(newDefaults) ⇒ void Override Evernode default configs. **Kind**: static method of [Defaults](#Defaults) @@ -3150,6 +3355,10 @@ Override Evernode default configs. | --- | --- | --- | | newDefaults | object | Configurations to override `{ governorAddress: '{string} governor xrpl address', rippledServer: '{string} rippled server url', xrplApi: '{XrplApi} xrpl instance', stateIndexId: '{string} firestore index', networkID: '{number} rippled network id' }` | +**Example** +```js +Defaults.set({governorAddress: 'rGVHr1PrfL93UAjyw3DWZoi9adz2sLp2yL'}); +``` ## EncryptionHelper @@ -5187,3 +5396,85 @@ For more details: https://js.xrpl.org/functions/multisign.html | --- | --- | --- | | transactions | Array.<(string\|object)> | An array of signed transactions, either as serialized strings or transaction objects, to combine into a single multi-signed transaction. | + + +## GovernorEvents +Following governor-specific events can be subscribed from Evernode client instances. + +**Kind**: global constant +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| Initialized | string | Triggered when governor receives a hook initialization. | +| CandidateProposed | string | Triggered when governor receives a new candidate proposal. | +| CandidateWithdrawn | string | Triggered when candidate withdrawal is requested. | +| ChildHookUpdated | string | Triggered when registry or heartbeat hook is updated. | +| GovernanceModeChanged | string | Triggered when governor receives a request to change the governance mode. | +| DudHostReported | string | Triggered when dud host is reported. | +| DudHostRemoved | string | Triggered when dud host is removed. | +| DudHostStatusChanged | string | Triggered when dud host candidate election status is changed. | +| FallbackToPiloted | string | Triggered when governance mode is changed to piloted mode. | +| NewHookStatusChanged | string | Triggered when new hook candidate election status is changed. | +| LinkedDudHostCandidateRemoved | string | Triggered when a host related to dud host candidate is removed by de-registration/transfer or prune. | + + + +## HeartbeatEvents +Following heartbeat-specific events can be subscribed from Evernode client instances. + +**Kind**: global constant +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| Heartbeat | string | Triggered when a heartbeat from a host is received. | +| FoundationVoted | string | Triggered when foundation vote for a candidate is received. | + + + +## RegistryEvents +Following registry-specific events can be subscribed from Evernode client instances. + +**Kind**: global constant +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| HostRegistered | string | Triggered when host registration event is received to the registry. | +| HostDeregistered | string | Triggered when host de-registration event is received to the registry. | +| HostRegUpdated | string | Triggered when host sends an update info request. | +| DeadHostPrune | string | Triggered when dead host prune request is received to the registry. | +| HostTransfer | string | Triggered when host transfer is requested by the host. | +| HostRebate | string | Triggered when host rebate is requested by the host. | +| HostReputationUpdated | string | Triggered when host reputation is updated. | + + + +## HostEvents +Following host-specific events can be subscribed from Evernode client instances. + +**Kind**: global constant +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| AcquireLease | string | Triggered when the host receives a lease acquire request. | +| ExtendLease | string | Triggered when the host receives a lease extend request. | +| TerminateLease | string | Triggered when the host receives a lease termination request. | + + + +## TenantEvents +Following tenant-specific events can be subscribed from Evernode client instances. + +**Kind**: global constant +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| AcquireSuccess | string | Triggered when the tenant receives an acquire success response. | +| AcquireError | string | Triggered when the tenant receives an acquire error response. | +| ExtendSuccess | string | Triggered when the tenant receives an extend success response. | +| ExtendError | string | Triggered when the tenant receives an extend error response. | + diff --git a/src/clients/base-evernode-client.js b/src/clients/base-evernode-client.js index 4ca6a3f..45fd04e 100644 --- a/src/clients/base-evernode-client.js +++ b/src/clients/base-evernode-client.js @@ -105,6 +105,7 @@ class BaseEvernodeClient { /** * Connects the client to xrpl server and do the config loading and subscriptions. 'subscribe' is called inside this. * @returns Boolean value `true` if the connection is successful. + * @example const status = await client.connect(); */ async connect(options = {}) { if (this.connected) @@ -129,6 +130,7 @@ class BaseEvernodeClient { /** * Disconnects the client to xrpl server and do the un-subscriptions. 'unsubscribe' is called inside this. + * @example await client.disconnect(); */ async disconnect() { await this.unsubscribe(); diff --git a/src/clients/foundation-client.js b/src/clients/foundation-client.js index ab009a1..3b86ae9 100644 --- a/src/clients/foundation-client.js +++ b/src/clients/foundation-client.js @@ -13,6 +13,9 @@ const REPUTATION_HOST_ADDRESS_PARAM_OFFSET = 0; const REPUTATION_VALUE_PARAM_OFFSET = 20; const REPUTATION_PARAM_SIZE = 21; +/** + * Foundation Events + */ const FoundationEvents = {} /** diff --git a/src/clients/hook-clients/governor-client.js b/src/clients/hook-clients/governor-client.js index aa402f8..90d3275 100644 --- a/src/clients/hook-clients/governor-client.js +++ b/src/clients/hook-clients/governor-client.js @@ -2,6 +2,20 @@ const { BaseEvernodeClient } = require("../base-evernode-client"); const { Defaults } = require("../../defaults"); const { EvernodeEvents } = require('../../evernode-common'); +/** + * Following governor-specific events can be subscribed from Evernode client instances. + * @property {string} Initialized - Triggered when governor receives a hook initialization. + * @property {string} CandidateProposed - Triggered when governor receives a new candidate proposal. + * @property {string} CandidateWithdrawn - Triggered when candidate withdrawal is requested. + * @property {string} ChildHookUpdated - Triggered when registry or heartbeat hook is updated. + * @property {string} GovernanceModeChanged - Triggered when governor receives a request to change the governance mode. + * @property {string} DudHostReported - Triggered when dud host is reported. + * @property {string} DudHostRemoved - Triggered when dud host is removed. + * @property {string} DudHostStatusChanged - Triggered when dud host candidate election status is changed. + * @property {string} FallbackToPiloted - Triggered when governance mode is changed to piloted mode. + * @property {string} NewHookStatusChanged - Triggered when new hook candidate election status is changed. + * @property {string} LinkedDudHostCandidateRemoved - Triggered when a host related to dud host candidate is removed by de-registration/transfer or prune. + */ const GovernorEvents = { Initialized: EvernodeEvents.Initialized, CandidateProposed: EvernodeEvents.CandidateProposed, @@ -19,10 +33,19 @@ const GovernorEvents = { /** * GovernorClient is responsible for managing governor operations in Evernode. * It interacts with the XRP Ledger using the governor address and listens for specific governor events. - * * @extends BaseEvernodeClient */ class GovernorClient extends BaseEvernodeClient { + /** + * Creates an instance of GovernorClient. + * @param {Object} [options={}] - A JSON object of options for initializing the GovernorClient. + * @param {string} [options.governorAddress] - (Optional) The Governor Hook Account Xahau address. + * If not provided, the address from the 'Defaults' configuration will be used. + * @example + * const governorClient = new GovernorClient({ + * governorAddress: "rGVHr1PrfL93UAjyw3DWZoi9adz2sLp2yL" + * }); + */ constructor(options = {}) { super((options.governorAddress || Defaults.values.governorAddress), null, Object.values(GovernorEvents), false, options); } diff --git a/src/clients/hook-clients/heartbeat-client.js b/src/clients/hook-clients/heartbeat-client.js index 5a7551f..dccb0b0 100644 --- a/src/clients/hook-clients/heartbeat-client.js +++ b/src/clients/hook-clients/heartbeat-client.js @@ -1,6 +1,11 @@ const { BaseEvernodeClient } = require("../base-evernode-client"); const { EvernodeEvents } = require('../../evernode-common'); +/** + * Following heartbeat-specific events can be subscribed from Evernode client instances. + * @property {string} Heartbeat - Triggered when a heartbeat from a host is received. + * @property {string} FoundationVoted - Triggered when foundation vote for a candidate is received. + */ const HeartbeatEvents = { Heartbeat: EvernodeEvents.Heartbeat, FoundationVoted: EvernodeEvents.FoundationVoted @@ -9,10 +14,20 @@ const HeartbeatEvents = { /** * HeartbeatClient is responsible for managing heartbeat operations in Evernode. * It interacts with the XRP Ledger using the heartbeat address and listens for specific heartbeat events. - * * @extends BaseEvernodeClient */ class HeartbeatClient extends BaseEvernodeClient { + /** + * Creates an instance of HeartbeatClient. + * @param {Object} [options={}] - A JSON object of options for initializing the HeartbeatClient. + * @param {string} options.heartbeatAddress - The Heartbeat Hook Account Xahau address. + * @param {string} [options.rippledServer] - (Optional) The Rippled server URL. + * @example + * const heartbeatClient = new HeartbeatClient({ + * heartbeatAddress: 'raPSFU999HcwpyRojdNh2i96T22gY9fgxL', + * rippledServer: 'wss://hooks-testnet-v3.xrpl-labs.com' + * }); + */ constructor(options = {}) { super(options.heartbeatAddress, null, Object.values(HeartbeatEvents), false, options); } diff --git a/src/clients/hook-clients/hook-client-factory.js b/src/clients/hook-clients/hook-client-factory.js index 4f718fb..3f3c57c 100644 --- a/src/clients/hook-clients/hook-client-factory.js +++ b/src/clients/hook-clients/hook-client-factory.js @@ -6,8 +6,20 @@ const { ReputationClient } = require("./reputation-client"); /** * A factory class for creating different types of hook clients based on the provided hook type. + * @summary + * In Evernode, there are three distinct types of hooks: + * + * - Governor Hook + * - Registry Hook + * - Heartbeat Hook + * - Reputation Hook + * + * Each of these hooks is associated with a separate Xahau account. Therefore, in various scenarios, it becomes necessary to create client instances to engage with these hooks. + * This section aims to enhance your comprehension of the available hook clients in Evernode. It will provide you with detailed specifications and guidance on how to utilize them effectively within Evernode. + * The Hook Client Factory provides a common interface for creating hook clients. Developers can instantiate hook clients with minimal effort. * @class */ + class HookClientFactory { /** * Creates a hook client from given type. @@ -15,6 +27,12 @@ class HookClientFactory { * @param {Object} [options={}] - Optional configuration for the hook client. * @returns {Promise} - Returns a promise that resolves to an instance of the requested HookClient type, or `null` if the type is unsupported. * @throws {Error} Will throw an error if there is an issue connecting to the GovernorClient or obtaining the necessary configuration. + * @example + * Defaults.set({governorAddress: "rGVHr1PrfL93UAjyw3DWZoi9adz2sLp2yL"}); + * const governorClient = await HookClientFactory.create(HookTypes.governor); + * const registryClient = await HookClientFactory.create(HookTypes.registry); + * const heartbeatClient = await HookClientFactory.create(HookTypes.heartbeat); + * const reputationClient = await HookClientFactory.create(HookTypes.reputation); */ static async create(hookType, options = {}) { let governorClient; diff --git a/src/clients/hook-clients/registry-client.js b/src/clients/hook-clients/registry-client.js index f539951..1c005bb 100644 --- a/src/clients/hook-clients/registry-client.js +++ b/src/clients/hook-clients/registry-client.js @@ -1,6 +1,16 @@ const { BaseEvernodeClient } = require("../base-evernode-client"); const { EvernodeEvents } = require('../../evernode-common'); +/** + * Following registry-specific events can be subscribed from Evernode client instances. + * @property {string} HostRegistered - Triggered when host registration event is received to the registry. + * @property {string} HostDeregistered - Triggered when host de-registration event is received to the registry. + * @property {string} HostRegUpdated - Triggered when host sends an update info request. + * @property {string} DeadHostPrune - Triggered when dead host prune request is received to the registry. + * @property {string} HostTransfer - Triggered when host transfer is requested by the host. + * @property {string} HostRebate - Triggered when host rebate is requested by the host. + * @property {string} HostReputationUpdated - Triggered when host reputation is updated. + */ const RegistryEvents = { HostRegistered: EvernodeEvents.HostRegistered, HostDeregistered: EvernodeEvents.HostDeregistered, @@ -14,11 +24,21 @@ const RegistryEvents = { /** * RegistryClient is responsible for managing registry operations in Evernode. * It interacts with the XRP Ledger using the registry address and listens for specific registry events. - * * @extends BaseEvernodeClient */ class RegistryClient extends BaseEvernodeClient { + /** + * Creates an instance of RegistryClient. + * @param {Object} [options={}] - A JSON object of options for initializing the RegistryClient. + * @param {string} options.registryAddress - The Registry Hook Account Xahau address. + * @param {string} [options.rippledServer] - (Optional) The Rippled server URL. + * @example + * const registryClient = new RegistryClient({ + * registryAddress: 'rQUhXd7sopuga3taru3jfvc1BgVbscrb1X', + * rippledServer: 'wss://hooks-testnet-v3.xrpl-labs.com' + * }); + */ constructor(options = {}) { super(options.registryAddress, null, Object.values(RegistryEvents), false, options); } diff --git a/src/clients/hook-clients/reputation-client.js b/src/clients/hook-clients/reputation-client.js index 8cb3057..f858af8 100644 --- a/src/clients/hook-clients/reputation-client.js +++ b/src/clients/hook-clients/reputation-client.js @@ -6,11 +6,19 @@ const ReputationEvents = {} /** * ReputationClient is responsible for managing reputation operations in Evernode. * It interacts with the XRP Ledger using the reputation address and listens for specific reputation events. - * * @extends BaseEvernodeClient */ class ReputationClient extends BaseEvernodeClient { + /** + * Creates an instance of ReputationClient. + * @param {Object} [options={}] - A JSON object of options for initializing the ReputationClient. + * @param {string} options.reputationAddress - The Reputation Hook Account Xahau address. + * @example + * const reputationClient = new reputationAddress({ + * reputationAddress: 'rQUhXd7sopuga3taru3jfvc1BgVbscrb1X', + * }); + */ constructor(options = {}) { super(options.reputationAddress, null, Object.values(ReputationEvents), false, options); } diff --git a/src/clients/host-client.js b/src/clients/host-client.js index 500c347..22ee48d 100644 --- a/src/clients/host-client.js +++ b/src/clients/host-client.js @@ -15,6 +15,12 @@ const { UtilHelpers } = require('../util-helpers'); const OFFER_WAIT_TIMEOUT = 60; +/** + * Following host-specific events can be subscribed from Evernode client instances. + * @property {string} AcquireLease - Triggered when the host receives a lease acquire request. + * @property {string} ExtendLease - Triggered when the host receives a lease extend request. + * @property {string} TerminateLease - Triggered when the host receives a lease termination request. + */ const HostEvents = { AcquireLease: EvernodeEvents.AcquireLease, ExtendLease: EvernodeEvents.ExtendLease, @@ -73,7 +79,6 @@ class HostClient extends BaseEvernodeClient { /** * Creates an instance of HostClient. - * * @param {string} xrpAddress - The XRP address to associate with this client. * @param {string} xrpSecret - The secret (private key) associated with the XRP address. * @param {Object} [options={}] - Additional configuration options for the HostClient. @@ -88,6 +93,11 @@ class HostClient extends BaseEvernodeClient { return res; } + /** + * Set reputation account detatils. + * @param {string} [reputationAddress = null] - XRPL address of the reputation account. + * @param {string} [reputationSecret = null] - XRPL secret of the reputation account. + */ async setReputationAcc(reputationAddress = null, reputationSecret = null) { let hostReputationAccId; if (!reputationAddress && !reputationSecret) { @@ -138,7 +148,7 @@ class HostClient extends BaseEvernodeClient { /** * Get lease token by index. - * @param index Index of the token. + * @param {string}index Index of the token. * @returns Lease token. */ async getLeaseByIndex(index) { diff --git a/src/clients/tenant-client.js b/src/clients/tenant-client.js index 0d64b9b..43301e8 100644 --- a/src/clients/tenant-client.js +++ b/src/clients/tenant-client.js @@ -10,6 +10,13 @@ const { XrplConstants } = require('../xrpl-common'); const DEFAULT_WAIT_TIMEOUT = 300000; +/** + * Following tenant-specific events can be subscribed from Evernode client instances. + * @property {string} AcquireSuccess - Triggered when the tenant receives an acquire success response. + * @property {string} AcquireError - Triggered when the tenant receives an acquire error response. + * @property {string} ExtendSuccess - Triggered when the tenant receives an extend success response. + * @property {string} ExtendError - Triggered when the tenant receives an extend error response. + */ const TenantEvents = { AcquireSuccess: EvernodeEvents.AcquireSuccess, AcquireError: EvernodeEvents.AcquireError, @@ -26,9 +33,16 @@ class TenantClient extends BaseEvernodeClient { /** * Creates an instance of TenantClient. - * @param {string} xrpAddress - The XRP address to associate with this client. - * @param {string} xrpSecret - The secret (private key) associated with the XRP address. - * @param {Object} [options={}] - Additional configuration options for the TenantClient. + * @param {string} xrpAddress - Xahau wallet address of the tenant. + * @param {string} xrpSecret - Secret key of the tenant's Xahau wallet. + * @param {Object} [options={}] - (Optional) A JSON object of options that can include the following properties. + * @param {string} [options.governorAddress] - (Optional) The Governor Hook Account Xahau address. + * @param {string} [options.rippledServer] - (Optional) The Rippled server URL. + * @example + * const client = new TenantClient("rKfHBc8e1VemZPLZoPXB7HjSKU2QjkRfP", "sszyYJ79AdUUF6dR7QfD9ARWfVuz3", { + * governorAddress: "rGVHr1PrfL93UAjyw3DWZoi9adz2sLp2yL", + * rippledServer: "wss://hooks-testnet-v3.xrpl-labs.com" + * }); */ constructor(xrpAddress, xrpSecret, options = {}) { super(xrpAddress, xrpSecret, Object.values(TenantEvents), false, options); @@ -219,11 +233,65 @@ class TenantClient extends BaseEvernodeClient { } /** - * Acquire an instance from a host - * @param {string} hostAddress XRPL address of the host to acquire the lease. - * @param {object} requirement The instance requirements and configuration. - * @param {object} options [Optional] Options for the XRPL transaction. - * @returns An object including transaction details,instance info, and acquireReference Id. + * Acquires an available instance on a specified host. + * @async + * @param {string} hostAddress - The wallet address of the host where the HotPocket instance will be created. + * @param {Object} requirement - The details necessary for creating the instance. + * @param {string} requirement.owner_pubkey - The public key of the tenant. + * @param {string} requirement.contract_id - The unique contract identifier. + * @param {string} requirement.image - The image used to create the HotPocket instance. + * @param {Object} requirement.config - Configuration object for the instance. + * @param {Object} [options={}] - Optional configurations for the transaction. + * @param {number} [options.timeout=60000] - Timeout for the transaction in milliseconds. + * @param {string} [options.leaseOfferIndex] - The index of the preferred lease offer from the host. + * @param {Object} [options.transactionOptions] - Options for the URITokenBuy transaction as defined in the Xahau documentation. + * @returns {Promise} Resolves with an object containing the transaction details and instance details. + * @returns {Object} transaction - Information about the transaction. + * @returns {string} transaction.Account - The address of the account initiating the transaction. + * @returns {string} transaction.Amount - The amount of currency transferred. + * @returns {string} transaction.Destination - The tenant's account address. + * @returns {string} transaction.Fee - The fee paid for the transaction, in EVR drops. + * @returns {number} transaction.LastLedgerSequence - The latest ledger sequence for the transaction. + * @returns {Object[]} transaction.Memos - Array of memo objects. + * @returns {string} transaction.hash - The SHA-512 hash of the transaction. + * @returns {number} transaction.ledger_index - The ledger index containing the transaction. + * @returns {string} transaction.DeliveredAmount - The actual amount delivered to the destination. + * @returns {Object} instance - Information about the acquired instance. + * @returns {string} instance.name - The unique identifier (URITokenID) of the instance. + * @returns {string} instance.pubkey - The public key of the instance. + * @returns {string} instance.contract_id - The unique contract identifier. + * @returns {string} instance.peer_port - The port used for peer communication. + * @returns {string} instance.user_port - The port used for user communication. + * @returns {string} instance.domain - The public domain of the host server. + * @returns {string} acquireRefId - The reference ID for the acquisition. + * @throws {Error} Throws an error if the acquisition fails. + * @throws {Object} error - The error object with details about the failure. + * @throws {string} error.error - The error code ('ACQUIRE_ERR'). + * @throws {string} error.reason - The reason for the acquisition failure. + * @throws {Object} error.transaction - The transaction details associated with the failed acquisition. + * @throws {string} error.transaction.Account - The tenant's account address. + * @throws {Object} error.transaction.Amount - The refund details. + * @throws {string} error.transaction.Amount.currency - The currency type (e.g., 'EVR'). + * @throws {string} error.transaction.Amount.issuer - The issuer of the currency. + * @throws {string} error.transaction.Amount.value - The value of the refunded amount. + * @throws {string} error.transaction.Destination - The tenant's account address. + * @throws {string} error.transaction.Fee - The transaction fee. + * @throws {Object[]} error.transaction.HookParameters - Contains event name and event data. + * @throws {string} error.transaction.HookParameters[].name - The event name (in hex format). + * @throws {string} error.transaction.HookParameters[].value - The event data (in hex format). + * @throws {string} error.acquireRefId - The reference ID for the failed acquisition request. + * @example + * const result = await tenant.acquireLease( + * "rnET2YR19WDP4vB8XtDhcF2J4afqMM6xim", + * { + * owner_pubkey: "ed5cb83404120ac759609819591ef839b7d222c84f1f08b3012f490586159d2b50", + * contract_id: "dc411912-bcdd-4f73-af43-32ec45844b9a", + * image: "evernodedev/sashimono:hp.latest-ubt.20.04-njs.16", + * config: {} + * }, + * { timeout: 10000 } + * ); + * console.log("Tenant received instance:", result); */ acquireLease(hostAddress, requirement, options = {}) { return new Promise(async (resolve, reject) => { diff --git a/src/defaults.js b/src/defaults.js index 8ddfd2d..6c8c89e 100644 --- a/src/defaults.js +++ b/src/defaults.js @@ -5,6 +5,9 @@ const DefinitionsUrl = 'https://raw.githubusercontent.com/EvernodeXRPL/evernode- const DefaultValues = { xrplApi: null } +/** + * The four Evernode hook types. governor,registry, heartbeat and reputation. + */ const HookTypes = { governor: 'GOVERNOR', @@ -51,6 +54,8 @@ class Defaults { /** * Override Evernode default configs. * @param {object} newDefaults Configurations to override `{ governorAddress: '{string} governor xrpl address', rippledServer: '{string} rippled server url', xrplApi: '{XrplApi} xrpl instance', stateIndexId: '{string} firestore index', networkID: '{number} rippled network id' }` + * @returns {void} + * @example Defaults.set({governorAddress: 'rGVHr1PrfL93UAjyw3DWZoi9adz2sLp2yL'}); */ static set(newDefaults) { Object.assign(DefaultValues, newDefaults) @@ -59,6 +64,7 @@ class Defaults { /** * Read Evernode default configs. * @returns The Object of Evernode configs + * @example const defaults = Defaults.values; */ static get values() { return { ...DefaultValues }; diff --git a/src/evernode-common.js b/src/evernode-common.js index 02b58e8..4a5e0ed 100644 --- a/src/evernode-common.js +++ b/src/evernode-common.js @@ -1,7 +1,10 @@ +/** + * Evernode constants +*/ const EvernodeConstants = { EVR: 'EVR', TOKEN_PREFIX_HEX: '657672686F7374', // evrhost - LEASE_TOKEN_PREFIX_HEX: '6576726C65617365', // evrlease + LEASE_TOKEN_PREFIX_HEX: '6576726C65617365', // evrlease LEASE_TOKEN_VERSION_PREFIX_HEX: '4C5456', // LTV (Lease_Token_Version) LEASE_TOKEN_VERSION: 1, HOOK_NAMESPACE: '01EAF09326B4911554384121FF56FA8FECC215FDDE2EC35D9E59F2C53EC665A0', @@ -41,6 +44,9 @@ const EvernodeConstants = { } } +/** + * Event types list in Evernode +*/ const EventTypes = { // Governor hook events. ACQUIRE_LEASE: 'evnAcquireLease', @@ -80,6 +86,9 @@ const EventTypes = { REPUTATION_CONTRACT_INFO_UPDATE: 'evnRepConInfoUpdate' } +/** + * Memo formats supported for use in transactions + */ const MemoFormats = { TEXT: 'text/plain', JSON: 'text/json', @@ -87,12 +96,18 @@ const MemoFormats = { HEX: 'hex' } +/** + * Error codes supported + */ const ErrorCodes = { ACQUIRE_ERR: 'ACQUIRE_ERR', EXTEND_ERR: 'EXTEND_ERR', PROPOSE_ERR: 'PROPOSE_ERR', } +/** + * Common reasons for errors that may occur + */ const ErrorReasons = { TRANSACTION_FAILURE: 'TRANSACTION_FAILURE', NO_OFFER: 'NO_OFFER', @@ -104,6 +119,9 @@ const ErrorReasons = { NO_STATE_KEY: 'NO_STATE_KEY' } +/** + * Reputation system constants used in the reputation calculation mechanisms + */ const ReputationConstants = { REP_INFO_BUFFER_SIZE: 43, REP_INFO_PUBKEY_OFFSET: 0, @@ -112,8 +130,11 @@ const ReputationConstants = { SCORE_EXPIRY_MOMENT_COUNT: 2 } -// All keys are prefixed with 'EVR' (0x455652) -// Config keys sub-prefix: 0x01 +/** + * Keys used to access and configure Evernode hook states + * All keys are prefixed with 'EVR' (0x455652) + * Config keys sub-prefix: 0x01 + */ const HookStateKeys = { // Configuration. EVR_ISSUER_ADDR: "4556520100000000000000000000000000000000000000000000000000000001", @@ -150,7 +171,10 @@ const HookStateKeys = { PREFIX_CANDIDATE_ID: "45565206", } -// All keys are prefixed with 'EVR' (0x455652) +/** + * Keys used to access specific parameters within Evernode hooks + * All keys are prefixed with 'EVR' (0x455652) + */ const HookParamKeys = { PARAM_STATE_HOOK_KEY: "4556520100000000000000000000000000000000000000000000000000000001", PARAM_EVENT_TYPE_KEY: "4556520100000000000000000000000000000000000000000000000000000002", @@ -158,6 +182,9 @@ const HookParamKeys = { PARAM_EVENT_DATA2_KEY: "4556520100000000000000000000000000000000000000000000000000000004", } +/** + * Events emitted by Evernode + */ const EvernodeEvents = { HostRegistered: "HostRegistered", HostDeregistered: "HostDeregistered", @@ -189,11 +216,17 @@ const EvernodeEvents = { HostReputationUpdated: "HostReputationUpdated" } +/** + * Types of URI tokens used within Evernode + */ const URITokenTypes = { LEASE_URI_TOKEN: 1, REGISTRATION_URI_TOKEN: 2 } +/** + * Regular expressions for validating data formats + */ const RegExp = { PublicPrivateKey: /^[0-9A-Fa-f]{66}$/ } diff --git a/src/state-helpers.js b/src/state-helpers.js index 3da783c..470b5c4 100644 --- a/src/state-helpers.js +++ b/src/state-helpers.js @@ -247,7 +247,6 @@ class StateHelpers { /** * Decodes a host address state from buffers. - * * @param {Buffer} stateKeyBuf - The buffer containing the state key. * @param {Buffer} stateDataBuf - The buffer containing the state data. * @returns {Object} The decoded host address state. @@ -289,7 +288,6 @@ class StateHelpers { /** * Decodes a token ID state from a buffer. - * * @param {Buffer} stateDataBuf - The buffer containing the state data. * @returns {Object} The decoded token ID state. */ @@ -309,7 +307,6 @@ class StateHelpers { /** * Decodes a transferee address state from buffers. - * * @param {Buffer} stateKeyBuf - The buffer containing the state key. * @param {Buffer} stateDataBuf - The buffer containing the state data. * @returns {Object} The decoded transferee address state. @@ -327,7 +324,6 @@ class StateHelpers { /** * Decodes a candidate owner state from buffers. - * * @param {Buffer} stateKeyBuf - The buffer containing the state key. * @param {Buffer} stateDataBuf - The buffer containing the state data. * @returns {Object} The decoded candidate owner state. @@ -347,7 +343,6 @@ class StateHelpers { /** * Decodes a candidate ID state from a buffer. - * * @param {Buffer} stateDataBuf - The buffer containing the state data. * @returns {Object} The decoded candidate ID state. */ @@ -387,7 +382,6 @@ class StateHelpers { /** * Decodes state data based on the state key and state data buffers. - * * @param {Buffer} stateKey - The buffer containing the state key. * @param {Buffer} stateData - The buffer containing the state data. * @returns {Object} The decoded state data with type information. @@ -639,7 +633,6 @@ class StateHelpers { /** * Decodes a state key into a type and key. - * * @param {Buffer} stateKey - The buffer containing the state key. * @returns {Object} An object containing the key as a hexadecimal string and its type. * @throws {Object} Throws a Validation Error if the state key is invalid. @@ -715,7 +708,6 @@ class StateHelpers { /** * Generates a state key for a token ID. - * * @param {string} uriToken - The URI token in hexadecimal format. * @returns {string} The generated state key as a hexadecimal string. */ @@ -731,7 +723,6 @@ class StateHelpers { /** * Generates a state key for a host address. - * * @param {string} address - The host address. * @returns {string} The generated state key as a hexadecimal string. */ @@ -751,7 +742,6 @@ class StateHelpers { /** * Generates a state key for a reputation host address. - * * @param {string} address - The reputation host address. * @returns {string} The generated state key as a hexadecimal string. */ @@ -764,7 +754,6 @@ class StateHelpers { /** * Generates a state key for a reputation host order address. - * * @param {string} address - The reputation host address. * @param {number} moment - The moment timestamp. * @returns {string} The generated state key as a hexadecimal string. @@ -780,7 +769,6 @@ class StateHelpers { /** * Generates a state key for a reputation host ordered ID. - * * @param {string} orderedId - The ordered ID. * @param {number} moment - The moment timestamp. * @returns {string} The generated state key as a hexadecimal string. @@ -796,7 +784,6 @@ class StateHelpers { /** * Generates a state key for a reputation host count. - * * @param {number} moment - The moment timestamp. * @returns {string} The generated state key as a hexadecimal string. */ @@ -810,7 +797,6 @@ class StateHelpers { /** * Generates a state key for reputation contract information. - * * @param {string} address - The contract address. * @returns {string} The generated state key as a hexadecimal string. */ @@ -826,7 +812,6 @@ class StateHelpers { /** * Generates a state key for a transferee address. - * * @param {string} address - The transferee address. * @returns {string} The generated state key as a hexadecimal string. */ @@ -846,7 +831,6 @@ class StateHelpers { /** * Generates a state key for a candidate ID. - * * @param {string} uniqueId - The unique candidate ID. * @returns {string} The generated state key as a hexadecimal string. */ @@ -862,7 +846,6 @@ class StateHelpers { /** * Generates a state key for a candidate owner. - * * @param {string} owner - The candidate owner address. * @returns {string} The generated state key as a hexadecimal string. */ @@ -882,7 +865,6 @@ class StateHelpers { /** * Gets the hook state index for a specific hook account and state key. - * * @param {string} hookAccount - The hook account address. * @param {string} stateKey - The state key as a hexadecimal string. * @param {string} [hookNamespace=EvernodeConstants.HOOK_NAMESPACE] - The hook namespace. @@ -910,7 +892,6 @@ class StateHelpers { /** * Generates a new hook candidate ID based on hash buffers. - * * @param {Buffer} hashesBuf - The buffer containing the hash data. * @returns {string} The generated candidate ID as a hexadecimal string. */ @@ -923,7 +904,6 @@ class StateHelpers { /** * Generates a candidate ID for the piloted mode. - * * @returns {string} The generated candidate ID as a hexadecimal string. */ static getPilotedModeCandidateId() { @@ -935,7 +915,6 @@ class StateHelpers { /** * Generates a candidate ID for a dud host. - * * @param {string} hostAddress - The host address. * @returns {string} The generated candidate ID as a hexadecimal string. */ @@ -948,7 +927,6 @@ class StateHelpers { /** * Retrieves the candidate type from a candidate ID. - * * @param {string} candidateId - The candidate ID as a hexadecimal string. * @returns {number} The candidate type. */ diff --git a/src/transaction-helper.js b/src/transaction-helper.js index fcba2cb..714018c 100644 --- a/src/transaction-helper.js +++ b/src/transaction-helper.js @@ -7,7 +7,6 @@ class TransactionHelper { /** * Converts an array of memos from the internal format to the XRPL library format. - * * @param {Array} memos - An array of memo objects in the internal format. * @returns {Array} An array of memo objects in the XRPL library format. */ @@ -27,7 +26,6 @@ class TransactionHelper { /** * Converts an array of memos from the XRPL library format to the internal format. - * * @param {Array} memos - An array of memo objects in the XRPL library format. * @returns {Array} An array of memo objects in the internal format. */ @@ -49,7 +47,6 @@ class TransactionHelper { /** * Converts an array of hook parameters from the internal format to the XRPL library format. - * * @param {Array} params - An array of hook parameter objects in the internal format. * @returns {Array} An array of hook parameter objects in the XRPL library format. */ @@ -68,7 +65,6 @@ class TransactionHelper { /** * Converts an array of hook parameters from the XRPL library format to the internal format. - * * @param {Array} params - An array of hook parameter objects in the XRPL library format. * @returns {Array} An array of hook parameter objects in the internal format. */ @@ -88,7 +84,6 @@ class TransactionHelper { /** * Converts a hexadecimal string to an ASCII string. - * * @param {string} hex - The hexadecimal string to be converted. * @returns {string} The resulting ASCII string. */ @@ -101,7 +96,6 @@ class TransactionHelper { /** * Converts an ASCII string to a hexadecimal string. - * * @param {string} str - The ASCII string to be converted. * @returns {string} The resulting hexadecimal string. */ diff --git a/src/util-helpers.js b/src/util-helpers.js index cb00164..74ae3e4 100644 --- a/src/util-helpers.js +++ b/src/util-helpers.js @@ -12,7 +12,6 @@ class UtilHelpers { /** * Decodes a lease token URI into its integrant parts. - * * @param {string} hexUri - The lease token URI in hexadecimal format. * @returns {Object} An object containing the decoded lease token URI's version, leaseIndex, halfTos, leaseAmount, identifier, and outboundIP */ @@ -55,7 +54,6 @@ class UtilHelpers { /** * Gets the current Unix time. - * * @param {string} [format="sec"] - The format of the time. If "sec", returns the time in seconds; otherwise, returns the time in milliseconds. * @returns {number} The current Unix time in the specified format. */ @@ -71,7 +69,6 @@ class UtilHelpers { /** * Derives a keypair from a given secret. - * * @param {string} secret - The secret used to derive the keypair. * @returns {Object} An object containing the derived keypair. */ @@ -81,7 +78,6 @@ class UtilHelpers { /** * Derives an address from a given public key. - * * @param {string} publicKey - The public key used to derive the address. * @returns {string} The derived address. */ diff --git a/src/xrpl-account.js b/src/xrpl-account.js index f63514b..637f400 100644 --- a/src/xrpl-account.js +++ b/src/xrpl-account.js @@ -282,15 +282,6 @@ class XrplAccount { * @returns {Promise} The prepared AccountSet transaction. */ async prepareSetAccountFields(fields, options = {}) { - /** - * Example for fields - * - * fields = { - * Domain : "www.mydomain.com", - * Flags : { asfDefaultRipple: false, asfDisableMaster: true } - * } - * - */ if (!options?.allowEmptyAccountSet && Object.keys(fields ?? {}).length === 0) throw "AccountSet fields cannot be empty."; diff --git a/src/xrpl-api.js b/src/xrpl-api.js index 2ae280d..72d096d 100644 --- a/src/xrpl-api.js +++ b/src/xrpl-api.js @@ -867,7 +867,6 @@ class XrplApi { /** * Joins the given array of signed transactions into one multi-signed transaction. * For more details: https://js.xrpl.org/functions/multisign.html - * * @param {Array} transactions - An array of signed transactions, either as serialized strings or transaction objects, to combine into a single multi-signed transaction. * @returns {string} A single multi-signed transaction in string format that contains all signers from the input transactions. * @throws {Error} If the transactions array is empty. diff --git a/src/xrpl-common.js b/src/xrpl-common.js index dd8e8a5..695616e 100644 --- a/src/xrpl-common.js +++ b/src/xrpl-common.js @@ -1,3 +1,6 @@ +/** + * Events emitted by XRPL API to track ledger and transaction activities + */ const XrplApiEvents = { LEDGER: 'ledger', DISCONNECTED: 'disconnected', @@ -9,6 +12,9 @@ const XrplApiEvents = { SERVER_DESYNCED: 'desynced' } +/** + * Constants used within the XRPL network and transactions + */ const XrplConstants = { MAX_LEDGER_OFFSET: 10, XRP: 'XRP', @@ -17,6 +23,9 @@ const XrplConstants = { MIN_DROPS: '1' } +/** + * Types of transactions supported in XRPL + */ const XrplTransactionTypes = { INVOKE: 'Invoke', PAYMENT: 'Payment',