From ffda89578e498d221adb4748761f94f64f06baef Mon Sep 17 00:00:00 2001 From: tripathyr Date: Sun, 8 Oct 2023 13:37:55 +0530 Subject: [PATCH] Adding the documentation for functions --- docs/client.md | 365 +++++++++++++++++++++++++++ docs/cloud.md | 108 ++++++++ docs/dboperations.md | 589 +++++++++++++++++++++++++++++++++++++++++++ docs/intra.md | 526 ++++++++++++++++++++++++++++++++++++++ docs/main.md | 322 +++++++++++++++++++++++ docs/server.md | 97 +++++++ docs/sync.md | 270 ++++++++++++++++++++ 7 files changed, 2277 insertions(+) create mode 100644 docs/client.md create mode 100644 docs/cloud.md create mode 100644 docs/dboperations.md create mode 100644 docs/intra.md create mode 100644 docs/main.md create mode 100644 docs/server.md create mode 100644 docs/sync.md diff --git a/docs/client.md b/docs/client.md new file mode 100644 index 0000000..f63ddcb --- /dev/null +++ b/docs/client.md @@ -0,0 +1,365 @@ +### `processIncomingData(data)` + +`processIncomingData(data)`, handles incoming data received by the server. Here's an explanation of the logic implemented in this function: + +#### Functionality: + +- The function takes a JSON-formatted `data` object as input, representing incoming data from clients. +- It performs several checks and processes the data based on its content and structure. +- The function distinguishes between different types of incoming data, such as requests, messages, tags, notes, and edits, and routes each type of data to the appropriate processing function. + +#### Logic Explanation: + +- **JSON Parsing:** + - The incoming `data` is first parsed as a JSON object. If parsing fails, an `INVALID` error is returned, indicating that the data is not in the correct JSON format. + +- **Time Validation:** + - The function checks the timestamp (`data.time`) included in the incoming data. If the timestamp is outside the valid time window (determined by `floGlobals.sn_config.delayDelta`), an `INVALID` error is returned, indicating an invalid time. + +- **Data Routing:** + - The function examines the content of the parsed `data` object to identify its type: + - If the `data` object contains a `request` property, it is treated as a user request and routed to `processRequestFromUser(data.request)`. + - If the `data` object contains a `message` property, it is processed as stored data and routed to `processDataFromUser(data)`. + - Similarly, the function handles cases where `data` contains properties like `tag`, `note`, or `edit`. + - If the incoming data does not match any valid format, an `INVALID` error is returned, indicating invalid data format. + +- **Asynchronous Processing:** + - The processing of the incoming data is performed asynchronously using promises. The appropriate processing function is called based on the data type, and the processing result is resolved or rejected accordingly. + +- **Logging and Error Handling:** + - The function logs relevant information during processing, providing visibility into the server's actions. + - Errors, including `INVALID` errors, are logged or debugged as appropriate, and the corresponding error is rejected to indicate the failure in processing. + +#### Purpose and Usage: + +- The `processIncomingData(data)` function serves as a central entry point for handling diverse types of incoming data from clients. +- It ensures that incoming data is correctly formatted, within a valid time frame, and routed to the appropriate processing logic. +- By encapsulating the logic for processing various data types, this function enhances the server's ability to handle a wide range of client interactions and data submissions. +- Error handling and logging mechanisms provide valuable insights into potential issues and ensure a robust and reliable data processing workflow. + +This function plays a crucial role in enabling the server to interpret and respond to incoming data, facilitating seamless communication between clients and the server while maintaining data integrity and consistency. + +### `processDataFromUser(data)` + +`processDataFromUser(data)`, handles user messages received by the server and processes them for storage. Here's an explanation of the logic implemented in this function: + +#### Functionality: + +- The function takes a `data` object as input, representing a user message containing various attributes such as sender ID, receiver ID, timestamp, application, message type, message content, and digital signature. +- It performs multiple validation and verification checks on the incoming data to ensure its integrity and authenticity before storing it in the database. +- Upon successful validation and verification, the function adds the user message to the database, recording relevant details such as sender ID, receiver ID, message content, and digital signature. +- The function resolves with the processed data, including a unique vector clock identifier, indicating successful storage of the message. + +#### Logic Explanation: + +- **Data Validation:** + - The function first validates the integrity of the provided data, checking attributes such as `receiverID`, `senderID`, `pubKey`, `sign`, `message`, `comment`, and others. + - It ensures that the receiver ID and sender ID are valid FLO blockchain addresses. + - The function validates the digital signature (`sign`) using the sender's public key (`pubKey`) to verify the authenticity of the message. + +- **Data Storage:** + - If the data passes all validation and verification checks, it is added to the database using the `DB.addData` function. The data stored includes sender ID, receiver ID, timestamp, application, message type, message content, digital signature, and a vector clock identifier generated based on the current timestamp and sender ID. + +- **Database Interaction:** + - After storing the data, the function retrieves the stored data from the database using `DB.getData` based on the unique vector clock identifier. It resolves with an array containing the stored data, message type ('DATA'), and the database response object. + +- **Error Handling:** + - If any validation or database-related operation fails, the function rejects the promise with an `INVALID` error or the specific error encountered during the process. + +#### Purpose and Usage: + +- `processDataFromUser(data)` plays a crucial role in processing and storing user messages submitted to the server. +- It ensures the integrity, authenticity, and secure storage of user-generated content in the database. +- By validating digital signatures and performing rigorous checks, the function prevents unauthorized or tampered messages from being accepted and stored. +- The unique vector clock identifier enables efficient retrieval and referencing of stored messages. +- This function is essential for maintaining data consistency and security, allowing the server to handle user-generated content reliably and securely. + +This function is a fundamental component of the server's functionality, ensuring that user messages are processed, validated, and securely stored, contributing to a robust and trustworthy communication platform. + +### User Request Processing Function + +The provided JavaScript function, `processRequestFromUser(request)`, handles user requests sent to the server. Here's an explanation of the logic implemented in this function: + +#### Functionality: + +- The function takes a `request` object as input, representing a user request containing attributes such as receiver ID and other search parameters. +- It validates the provided `receiverID` to ensure it is a valid FLO blockchain address. +- The function identifies the closest supernode (`closeNode`) to the specified receiver ID using the `cloud.closestNode` function. +- It checks whether the identified supernode is in the list of serving nodes (`_list.serving`). If not, the function rejects the request, indicating an incorrect supernode. + +#### Data Retrieval and Resolution: + +- If the `receiverID` is valid and the corresponding supernode is correct, the function searches the database for data matching the user's request parameters using the `DB.searchData` function. +- The function resolves with an array containing the search results retrieved from the database, providing the user with the requested data. + +#### Error Handling: + +- If the `receiverID` is invalid or the supernode is incorrect, the function rejects the promise with an `INVALID` error, indicating an invalid request. +- If any database-related operation fails during the search, the function rejects the promise with the specific error encountered during the process. + +#### Purpose and Usage: + +- `processRequestFromUser(request)` is essential for handling user queries and search requests submitted to the server. +- It validates user input, ensuring that requests contain valid receiver IDs and are directed to the correct supernodes. +- The function enables users to retrieve specific data from the database by providing search parameters, enhancing the user experience by allowing targeted data access. +- By resolving with the search results, the function provides users with the requested data, facilitating seamless interaction with the server's database. +- Proper error handling ensures that invalid or unauthorized requests are rejected, maintaining the integrity and security of the data retrieval process. + +This function is a fundamental component of the server's functionality, enabling users to request and receive specific data from the server's database securely and efficiently. + +### `processEditFromUser(data)` + +The provided JavaScript function, `processEditFromUser(data)`, handles user requests to edit comments stored in the server's database. Here's an explanation of the logic implemented in this function: + +#### Functionality: + +- The function takes a `data` object as input, representing the edited comment data along with relevant metadata such as receiver ID, vector clock, and cryptographic signatures. +- It validates the provided `receiverID` to ensure it is a valid FLO blockchain address. +- The function identifies the closest supernode (`closeNode`) to the specified receiver ID using the `cloud.closestNode` function. +- It checks whether the identified supernode is in the list of serving nodes (`_list.serving`). If not, the function rejects the request, indicating an incorrect supernode. +- The function verifies the cryptographic signatures (`sign` and `re_sign`) associated with the request data to ensure their authenticity and integrity. + +#### Comment Editing and Verification: + +- If the `receiverID` is valid, the supernode is correct, and the signatures are valid, the function proceeds to retrieve the original comment data associated with the provided `vectorClock` using the `DB.getData` function. +- It checks whether the retrieved data exists in the database. If not, the function rejects the request, indicating an invalid `vectorClock`. +- The function verifies the `requestorID` and its associated public key (`pubKey`) to ensure they match the original comment data. If not, the request is rejected, indicating an invalid `requestorID` or `pubKey`. +- If all verifications pass, the function updates the comment content to the edited value provided in the `data.edit` field. If `data.edit` is `null`, indicating the intention to remove the comment, the function updates the comment with a `NULL` value in the database (equivalent to deletion in SQL). +- The edited comment data, along with relevant metadata, is then stored in the database using the `DB.editData` function. + +#### Resolving and Rejecting Promises: + +- If the editing process is successful, the function resolves with an array containing the edited comment data, the edit type (`'EDIT'`), and the updated data record from the database. +- If any validation or database-related operation fails, the function rejects the promise with a specific error message, indicating the type of validation failure encountered during the process. + +#### Purpose and Usage: + +- `processEditFromUser(data)` is essential for handling user requests to edit comments stored in the server's database. +- It ensures that the editing requests are legitimate, coming from the correct sender (`requestorID`) and are associated with the corresponding original comment data. +- The function allows users to modify their comments securely, maintaining data integrity and authenticity while facilitating interactive and dynamic content management within the server. +- Proper error handling guarantees that only valid and authorized comment edits are accepted, preserving the trustworthiness and reliability of the server's data. +- Users can edit their comments with confidence, knowing that their modifications are securely processed and stored in the server's database. + +This function plays a crucial role in enabling users to manage and update their comments, enhancing the interactive nature of the server's content while upholding data security and integrity. + +### `processTagFromUser(data)` + +The provided JavaScript function, `processTagFromUser(data)`, handles user requests to tag specific data entries stored in the server's database. Here's an explanation of the logic implemented in this function: + +#### Functionality: + +- The function takes a `data` object as input, representing the tag data along with relevant metadata such as receiver ID, vector clock, and cryptographic signatures. +- It validates the provided `receiverID` to ensure it is a valid FLO blockchain address. +- The function identifies the closest supernode (`closeNode`) to the specified receiver ID using the `cloud.closestNode` function. +- It checks whether the identified supernode is in the list of serving nodes (`_list.serving`). If not, the function rejects the request, indicating an incorrect supernode. +- The function verifies the cryptographic signatures (`sign`) associated with the request data to ensure their authenticity and integrity. + +#### Tagging Process and Verification: + +- If the `receiverID` is valid, the supernode is correct, and the signatures are valid, the function proceeds to retrieve the original data associated with the provided `vectorClock` using the `DB.getData` function. +- It checks whether the retrieved data exists in the database. If not, the function rejects the request, indicating an invalid `vectorClock`. +- The function verifies whether the application associated with the tagged data is authorized by checking if it is in the list of authorized applications (`floGlobals.appList`). +- It validates the `requestorID` against the list of sub-admins and trusted IDs associated with the application. If the `requestorID` is not valid, the function rejects the request, indicating an invalid `requestorID`. +- The function further validates the `pubKey` associated with the `requestorID`. +- If all verifications pass, the function updates the tag associated with the data entry to the provided `data.tag` value. If `data.tag` is `null`, indicating the intention to remove the tag, the function updates the tag with a `NULL` value in the database (equivalent to untagging in SQL). +- The tagged data, along with relevant metadata, is then stored in the database using the `DB.tagData` function. + +#### Resolving and Rejecting Promises: + +- If the tagging process is successful, the function resolves with an array containing the tagged data, the tag type (`'TAG'`), and the updated data record from the database. +- If any validation or database-related operation fails, the function rejects the promise with a specific error message, indicating the type of validation failure encountered during the process. + +#### Purpose and Usage: + +- `processTagFromUser(data)` is essential for handling user requests to tag specific data entries stored in the server's database. +- It ensures that tagging requests come from authorized sources (`requestorID` within the authorized sub-admins or trusted IDs for the corresponding application) and maintain data integrity and authenticity. +- The function allows authorized users to add or remove tags to specific data entries securely, enhancing data organization and categorization within the server. +- Proper error handling guarantees that only valid and authorized tagging operations are accepted, preserving the trustworthiness and reliability of the server's tagged data. +- Users can manage their tagged data with confidence, knowing that their tagging modifications are securely processed and stored in the server's database. + +This function plays a vital role in enabling users to categorize and organize their data effectively, providing a streamlined and organized approach to data management while upholding data security and integrity. + +### `processNoteFromUser(data)` + +The provided JavaScript function, `processNoteFromUser(data)`, handles user requests to add notes to specific data entries stored in the server's database. Here's an explanation of the logic implemented in this function: + +#### Functionality: + +- The function takes a `data` object as input, representing the note data along with relevant metadata such as receiver ID, vector clock, and cryptographic signatures. +- It validates the provided `receiverID` to ensure it is a valid FLO blockchain address. +- The function identifies the closest supernode (`closeNode`) to the specified receiver ID using the `cloud.closestNode` function. +- It checks whether the identified supernode is in the list of serving nodes (`_list.serving`). If not, the function rejects the request, indicating an incorrect supernode. +- The function verifies the cryptographic signatures (`sign`) associated with the request data to ensure their authenticity and integrity. + +#### Note Addition and Verification: + +- If the `receiverID` is valid, the supernode is correct, and the signatures are valid, the function proceeds to retrieve the original data associated with the provided `vectorClock` using the `DB.getData` function. +- It checks whether the retrieved data exists in the database. If not, the function rejects the request, indicating an invalid `vectorClock`. +- The function validates the `requestorID` against the list of sub-admins and trusted IDs associated with the application. If the `requestorID` is not valid, the function rejects the request, indicating an invalid `requestorID`. +- The function further validates the `pubKey` associated with the `requestorID`. +- If all verifications pass, the function updates the note associated with the data entry to the provided `data.note` value. If `data.note` is `null`, indicating the intention to remove the note, the function updates the note with a `NULL` value in the database (equivalent to removing the note in SQL). +- The noted data, along with relevant metadata, is then stored in the database using the `DB.noteData` function. + +#### Resolving and Rejecting Promises: + +- If the note addition process is successful, the function resolves with an array containing the noted data, the note type (`'NOTE'`), and the updated data record from the database. +- If any validation or database-related operation fails, the function rejects the promise with a specific error message, indicating the type of validation failure encountered during the process. + +#### Purpose and Usage: + +- `processNoteFromUser(data)` is essential for handling user requests to add notes to specific data entries stored in the server's database. +- It ensures that note addition requests come from authorized sources (`requestorID` within the authorized sub-admins or trusted IDs for the corresponding application) and maintain data integrity and authenticity. +- The function allows authorized users to add or remove notes to specific data entries securely, enhancing data documentation and context within the server. +- Proper error handling guarantees that only valid and authorized note addition operations are accepted, preserving the trustworthiness and reliability of the server's noted data. +- Users can document their data with confidence, knowing that their note additions are securely processed and stored in the server's database. + +This function plays a crucial role in enabling users to annotate and document their data effectively, providing a comprehensive and organized approach to data documentation while upholding data security and integrity. + +### `checkIfRequestSatisfy(request, data)` + +The provided JavaScript function, `checkIfRequestSatisfy(request, data)`, serves as a request validation mechanism for ensuring that a given request satisfies specific criteria before further processing. Here's an explanation of the logic implemented in this function: + +#### Functionality: + +- The function takes two parameters: `request` (representing the user's query or request) and `data` (representing the data entry to be validated against the request criteria). +- It evaluates various conditions specified in the `request` object to determine if the provided `data` entry meets the specified criteria. +- The function checks specific attributes within the `request` object against corresponding attributes in the `data` entry to validate if they match. + +#### Criteria and Validation: + +1. **Receiver ID and Proxy ID:** + - The function verifies that the receiver ID derived from the `request` object matches the proxy ID or receiver ID in the `data` object. If not, the function returns `false`. + +2. **Vector Clock:** + - If the `request` specifies an exact vector clock (`atVectorClock`), the function checks if it matches the vector clock in the `data` entry. If they differ, the function returns `false`. + - Similarly, the function checks if the `data` entry's vector clock falls within the specified range (`lowerVectorClock` and `upperVectorClock`) in the `request` object. If not, it returns `false`. + +3. **Timestamp:** + - The function compares the `afterTime` attribute in the `request` object with the `log_time` attribute in the `data` entry. If the `log_time` is earlier than the specified time, the function returns `false`. + +4. **Application, Comment, and Type:** + - The function validates if the `application`, `comment`, and `type` attributes in the `request` object match the corresponding attributes in the `data` entry. If any of these attributes do not match, the function returns `false`. + +5. **Sender ID:** + - If the `request` object contains a specific sender ID or an array of sender IDs, the function checks if the `senderID` attribute in the `data` entry matches any of these sender IDs. If not, it returns `false`. + +#### Result and Usage: + +- If all specified conditions within the `request` object are met by the `data` entry, the function returns `true`, indicating that the request criteria are satisfied by the provided data. +- If any condition fails to match, the function returns `false`, indicating that the provided data does not meet the specified request criteria. +- The function is utilized to filter and validate data entries based on user queries, ensuring that only relevant and matching data is processed further. +- By performing these checks, the function guarantees that the server processes user requests accurately and efficiently, enhancing the server's ability to respond to specific user queries with precise and relevant data. + +This request validation function is crucial for maintaining the integrity of user queries and data processing, ensuring that only valid and relevant data entries are considered for further operations. It enhances the server's functionality by enabling targeted and accurate responses to user queries while upholding the quality and relevance of the processed data. + +### `processStatusFromUser(request, ws)` + +The JavaScript function `processStatusFromUser(request, ws)` is responsible for processing status-related requests received from users over WebSocket connections. This function manages two main functionalities based on the content of the `request` object: + +#### Setting User Online Status: +- If the `request` object contains a `status` attribute, the function processes it as a request to set the user's online status. +- It validates the provided parameters in the `request` object, including `floID`, `application`, `sign`, `pubKey`, and `time`. +- The function verifies the authenticity of the request by validating the provided public key (`pubKey`) against the corresponding `floID` using cryptographic signatures. +- If the request passes all validations, the user's online status is updated using the `clientOnline` function. +- If any validation fails, an error message indicating the specific validation issue is sent back to the user via the WebSocket connection. + +#### Tracking Online Status: +- If the `request` object does not contain a `status` attribute, the function processes it as a request to track online status updates for specific users (`trackList`). +- It validates the `application` attribute and ensures that the `trackList` attribute is an array. +- If the request parameters are valid, the user is added to the tracking list for the specified application using the `addRequestClient` function. +- If the request parameters are invalid, an error message detailing the specific validation issue is sent back to the user via the WebSocket connection. + +#### Result and Usage: +- The function plays a crucial role in managing user online status and tracking specific users' status updates in real-time. +- By validating user requests and verifying their authenticity through cryptographic signatures, the function ensures the integrity and security of online status updates. +- Additionally, the function facilitates seamless communication between clients and the server, allowing users to set their online status and track the status of other users within specified applications. +- Through WebSocket connections, this function enables dynamic and interactive updates regarding user online presence, enhancing the overall user experience within the application. +- Proper validation and error handling mechanisms within this function contribute to the reliability and security of online status management, promoting a smooth and secure user interaction environment. + +### `clientOnline(ws, application, floID)` + +The JavaScript function `clientOnline(ws, application, floID)` is responsible for managing the online status of clients within a specific application. This function is invoked when a user establishes a WebSocket connection (`ws`) and intends to set their online status. Here's how the function operates: + +#### Process Flow: +- **Application Check:** The function first checks if the specified `application` exists within the `onlineClients` data structure. If not, it creates a new entry for the application to store client online statuses. +- **Online Status Update:** If the user's `floID` (unique identifier) is already registered as online for the given application, the function increments the online status count for that user. This count helps track multiple WebSocket connections from the same user. +- **New Online User:** If the user's `floID` is not found in the application's online clients list, the function registers the user as online, setting their online status count to 1. Additionally, the function triggers an event to inform other clients (`informRequestClients`) that a new user has come online. +- **WebSocket Close Handling:** The function sets up a close event listener on the WebSocket connection. If the WebSocket connection is closed, it triggers the `clientOffline` function to update the user's online status accordingly. + +#### Usage and Impact: +- The function ensures that clients are accurately tracked based on their online status within specific applications. +- By maintaining a count of active WebSocket connections per user (`floID`), the function can handle scenarios where a user might have multiple active connections simultaneously. +- Real-time communication mechanisms, such as informing other clients when a new user comes online, enhance user interaction and engagement within the application. +- WebSocket close event handling ensures that the server is promptly informed when a user disconnects, allowing for accurate tracking of online status changes. +- Overall, this function contributes to creating a dynamic and interactive user experience by managing client online statuses and facilitating real-time communication among users within the application. + +### `clientOffline(application, floID)` + +The JavaScript function `clientOffline(application, floID)` manages the offline status of clients within a specific application. When a user disconnects their WebSocket connection, this function is called to update the user's online status. Here's how the function works: + +#### Process Flow: +- **Application Check:** The function first verifies if the specified `application` exists within the `onlineClients` data structure. +- **User Check:** If the application is found, the function checks if the `floID` (unique identifier) of the disconnected user is registered as online for that application. +- **Decrementing Online Status:** If the user's `floID` is found and has an online status count greater than 1, indicating multiple active connections, the function decrements the user's online status count by 1. +- **Removing User:** If the user's `floID` is found and has an online status count of 1, indicating a single active connection (the one being closed), the function removes the user from the online clients list for the specified application. It also triggers an event to inform other clients (`informRequestClients`) that the user has gone offline. +- **Empty Application Handling:** After removing the user, the function checks if there are no remaining online users for the application. If so, it deletes the application entry from the `onlineClients` data structure to maintain cleanliness. + +#### Usage and Impact: +- The function ensures accurate tracking of client online status, allowing the server to promptly update user statuses when they disconnect from the application. +- By decrementing the online status count for users with multiple connections, the function handles scenarios where a user might close one of their active connections while keeping others open. +- Real-time communication mechanisms, such as informing other clients when a user goes offline, enhance user interaction and awareness within the application. +- Clean-up functionality ensures that the `onlineClients` data structure remains optimized, removing empty entries for applications with no online users. +- Overall, this function contributes to maintaining a dynamic and responsive user experience by managing client online statuses and facilitating real-time communication among users within the application. + +### `addRequestClient(ws, application, trackList)` + +The JavaScript function `addRequestClient(ws, application, trackList)` handles the addition of request clients and provides status updates to WebSocket connections. This function is essential for managing client tracking and informing clients about the online status of other users they are tracking. Here's how the function works: + +#### Process Flow: +- **Client Identification:** Upon receiving a new WebSocket connection (`ws`), the function generates a unique `id` based on the current timestamp and a random string. This `id` is used to identify the specific request client connection. +- **Application Check:** The function checks if the specified `application` exists within the `requestClients` data structure. If not, a new entry is created for the application. +- **Request Client Entry:** The function adds a new entry to the `requestClients` data structure for the given `application`. This entry includes the WebSocket connection (`ws`) and the `trackList`, which contains the `floID` values of other users the client wants to track. +- **Status Initialization:** The function initializes an empty `status` object to store the online status of the tracked users (`floID`) for the specified application. +- **Status Update:** For each `floID` in the `trackList`, the function checks if the user is online (`ONLINE`) or offline (`OFFLINE`) based on their status in the `onlineClients` data structure. The current status of each tracked user is added to the `status` object. +- **Status Transmission:** The function sends the `status` object as a JSON string to the newly connected client (`ws`). This informs the client about the online status of the users they are tracking. +- **Close Event Handling:** The function registers a close event for the WebSocket connection. When the client disconnects, the `rmRequestClient` function is called to remove the client from the `requestClients` data structure. + +#### Usage and Impact: +- The function facilitates the tracking of specific users (`floID`) by request clients, enabling them to receive real-time updates about the online status of these users within the application. +- By sending an initial status update upon connection, the function ensures that the client has the most recent online status information for the users they are tracking. +- Real-time status updates enhance user interaction and collaboration within the application, allowing clients to be aware of the online presence of other tracked users. +- The function's dynamic approach to tracking and status updates contributes to a responsive and engaging user experience, fostering seamless communication and user awareness within the application. + +### `rmRequestClient(application, id)` + +The JavaScript function `rmRequestClient(application, id)` is responsible for removing a specific request client from the `requestClients` data structure. When a WebSocket connection is closed, this function is called to clean up the associated data and ensure that resources are appropriately managed. Here's how the function operates: + +#### Process Flow: +- **Existence Check:** The function first checks if the specified `application` exists in the `requestClients` data structure and if the given `id` is associated with the application. +- **Removal:** If the application and client `id` are found, the corresponding entry is deleted from the `requestClients` data structure. +- **Empty Application Check:** After the removal, the function checks if there are any remaining entries for the given `application`. If not, indicating that there are no active request clients for this application, the application entry is deleted from the `requestClients` data structure. + +#### Impact and Cleanup: +- The function plays a crucial role in managing resources, ensuring that closed WebSocket connections are properly removed from the tracking system. +- By removing the disconnected clients, the application maintains an accurate and up-to-date record of active clients, preventing unnecessary resource usage. +- Efficient resource management enhances the overall stability and responsiveness of the application, optimizing its performance and user experience. +- The function's timely execution during WebSocket closure events contributes to the application's scalability and reliability, allowing it to handle a large number of clients without degradation in performance. + +### `informRequestClients(application, floID, status)` + +The JavaScript function `informRequestClients(application, floID, status)` is responsible for notifying specific request clients about the online or offline status change of a particular `floID` associated with a given `application`. This function ensures that the clients tracking the specified `floID` are informed about its status change. Here's how the function operates: + +#### Process Flow: +- **Existence Check:** The function checks if the specified `application` exists in the `requestClients` data structure. +- **Client Iteration:** If the application is found, the function iterates through the active request clients (`r`) registered for the given application. +- **Matching IDs:** For each client, the function checks if the client's `trackList` includes the target `floID`. If a match is found, indicating that the client is interested in tracking the specified `floID`, a message is sent to the client WebSocket connection with the updated status. +- **Notification Message:** The function constructs a JSON message containing the `floID` and its corresponding `status`, encapsulated within an object. This message is sent to the client using the WebSocket connection. + +#### Impact and Communication: +- The function plays a vital role in ensuring real-time communication between the server and specific clients interested in the online/offline status of particular `floID`s. +- By sending targeted status updates, the function enables clients to receive relevant information without unnecessary data transmission, optimizing network usage and client responsiveness. +- This targeted communication mechanism enhances the user experience by providing clients with timely updates about the status changes of the specific `floID`s they are monitoring. +- The function facilitates efficient tracking and management of user presence, enabling applications to implement features such as user availability indicators, friend online status notifications, and other dynamic real-time interactions. +- The timely and precise delivery of status updates enhances the overall interactivity and engagement of users within the application, fostering a seamless and responsive user experience. + + diff --git a/docs/cloud.md b/docs/cloud.md new file mode 100644 index 0000000..c0b4a40 --- /dev/null +++ b/docs/cloud.md @@ -0,0 +1,108 @@ +### `K_Bucket(masterID, nodeList)` + +This function creates a Kademlia K-bucket structure based on a given master node ID and a list of node IDs. It provides various methods for querying and manipulating nodes within the K-bucket. The K-bucket organizes nodes in a distributed network for efficient peer-to-peer communication and routing. + +#### Parameters + +- `masterID` (string): The node ID of the master node, used as a reference point for calculating distances between nodes. +- `nodeList` (array): An array of node IDs to be added to the K-bucket. + +#### Properties + +- `order` (Array): An array containing the node IDs in the K-bucket, sorted based on their proximity to the master node. + +#### Methods + +- `innerNodes(id1, id2)`: Returns an array of node IDs that are between the specified nodes `id1` and `id2` in the K-bucket. +- `outerNodes(id1, id2)`: Returns an array of node IDs that are outside the specified nodes `id1` and `id2` in the K-bucket. +- `prevNode(id, N)`: Returns the previous node ID in the K-bucket relative to the given node `id`. Optionally, you can specify the number `N` of previous nodes to retrieve. +- `nextNode(id, N)`: Returns the next node ID in the K-bucket relative to the given node `id`. Optionally, you can specify the number `N` of next nodes to retrieve. +- `closestNode(id, N)`: Returns the closest node ID(s) to the given node `id` in the K-bucket. Optionally, you can specify the number `N` of closest nodes to retrieve. + +#### Example Usage + +```javascript +const nodeList = ['node1', 'node2', 'node3', 'node4']; +const masterNodeID = 'masterNode'; + +const kBucket = new K_Bucket(masterNodeID, nodeList); + +const innerNodes = kBucket.innerNodes('node1', 'node3'); +console.log('Inner Nodes:', innerNodes); + +const outerNodes = kBucket.outerNodes('node1', 'node3'); +console.log('Outer Nodes:', outerNodes); + +const prevNode = kBucket.prevNode('node3'); +console.log('Previous Node:', prevNode); + +const nextNode = kBucket.nextNode('node3'); +console.log('Next Node:', nextNode); + +const closestNode = kBucket.closestNode('node2'); +console.log('Closest Node:', closestNode); + +``` + +### `proxyID(address)` + +This function generates a proxy ID (public key hash) from a given blockchain address. It supports legacy, Bech32, and public key hex formats and ensures the integrity of the address before generating the proxy ID. + +#### Parameters + +- `address` (string): The blockchain address from which the proxy ID is generated. + +#### Returns + +- `proxyID` (string): The generated proxy ID (public key hash) derived from the provided address. + +#### Throws + +- `Error`: Throws an error if the input address is invalid. + +#### Example Usage + +```javascript +const address = '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa'; // Example Bitcoin address +try { + const proxyId = proxyID(address); + console.log('Proxy ID:', proxyId); +} catch (error) { + console.error('Error:', error.message); +} +``` + +### Mechanism of Generating `proxyID` + +The `proxyID(address)` function generates a proxy ID (public key hash) from a given blockchain address using a specific mechanism. Here's how it works: + +1. **Address Validation:** + - The function first validates the input `address` to determine its format (legacy, Bech32, or public key hex). + +2. **Address Decoding:** + - If the input `address` is in legacy format (34 characters), the function decodes the address using Base58 encoding and removes the last 4 checksum bytes to obtain the raw public key. + - If the address is in Bech32 format (42 or 62 characters), it decodes the address, converts it to raw bytes, and adjusts the size if necessary. + - If the address is in public key hex format (66 characters), the function converts the hexadecimal representation to bytes. + +3. **Prefix Addition:** + - The function adds the blockchain-specific prefix (e.g., Bitcoin's prefix) to the beginning of the raw public key bytes. This prefix indicates the network and ensures uniqueness. + +4. **Double Hashing:** + - The concatenated bytes (public key with prefix) undergo a double hashing process. + - First, the bytes are hashed using the SHA-256 (Secure Hash Algorithm 256-bit). + - The resulting hash is hashed again using SHA-256, creating a double hash of 256 bits. + +5. **Checksum Addition:** + - The first 4 bytes of the double hash result are added as a checksum to the end of the original bytes. + - This ensures the integrity of the proxy ID and helps detect errors or tampering. + +6. **Base58 Encoding:** + - The final bytes, including the prefix and checksum, are encoded using Base58 encoding to generate the proxy ID. + - Base58 encoding ensures a more compact representation of the data, removing ambiguous characters like '0', 'O', 'I', and 'l'. + +7. **Proxy ID Output:** + - The generated Base58-encoded string represents the proxy ID, which is a unique and secure identifier derived from the original blockchain address. + +This mechanism guarantees the integrity of the proxy ID and its association with the given blockchain address. It allows systems to use proxy IDs for various purposes, such as identity verification and secure communication. + +**Note:** The specific blockchain prefix and checksum bytes ensure that the proxy ID is compatible with the target blockchain network and can be used reliably in decentralized applications. diff --git a/docs/dboperations.md b/docs/dboperations.md new file mode 100644 index 0000000..d0969af --- /dev/null +++ b/docs/dboperations.md @@ -0,0 +1,589 @@ +## Database Operations + +### `initConnection(user, password, dbname, host = 'localhost')` + +Initializes a connection to the database. + +### `queryResolve(sql, values)` + +Executes a SQL query with optional parameterized values and resolves with the query result. + +### `queryStream(sql, values, callback)` + +Executes a streaming SQL query with optional parameterized values and a callback function. + +### Base Tables + +#### `DB.createBase()` + +Creates base tables in the database if they do not already exist. + +#### `DB.setLastTx(id, n)` + +Inserts or updates the last transaction ID for a specified ID. + +#### `DB.setConfig(name, value)` + +Inserts or updates configuration values in the database. + +#### `DB.addSuperNode(id, pubKey, uri)` + +Inserts or updates a supernode entry in the database. + +#### `DB.rmSuperNode(id)` + +Removes a supernode entry from the database. + +#### `DB.updateSuperNode(id, uri)` + +Updates the URI of a supernode entry in the database. + +#### `DB.setSubAdmin(appName, subAdmins)` + +Sets sub-admins for an application. + +#### `DB.setTrustedIDs(appName, trustedIDs)` + +Sets trusted IDs for an application. + +#### `DB.addApp(appName, adminID)` + +Inserts or updates an application entry in the database. + +#### `DB.rmApp(appName)` + +Removes an application entry from the database. + +#### `DB.getBase()` + +Retrieves essential data from base tables. + +### Supernode Tables + +#### `DB.createTable(snID)` + +Creates a table for a specific supernode. + +#### `DB.dropTable(snID)` + +Drops the table for a specific supernode. + +#### `DB.listTable()` + +Lists all supernode tables in the database. + +#### Data Service (by client) + +##### `DB.addData(snID, data)` + +Adds data to the supernode table. + +##### `DB.editData(snID, vectorClock, comment, newSign)` + +Edits existing data in the supernode table. + +##### `DB.getData(snID, vectorClock)` + +Retrieves data from the supernode table. + +##### `DB.tagData(snID, vectorClock, tag, tagTime, tagKey, tagSign)` + +Tags data in the supernode table. + +##### `DB.noteData(snID, vectorClock, note, noteTime, noteKey, noteSign)` + +Adds a note to data in the supernode table. + +##### `DB.searchData(snID, request)` + +Searches data in the supernode table based on criteria. + +#### Backup Service + +##### `DB.lastLogTime(snID)` + +Retrieves the last log time from the supernode table. + +##### `DB.createGetLastLog(snID)` + +Creates a function to get the last log time for a specific supernode. + +##### `DB.readAllDataStream(snID, logtime, callback)` + +Reads all data from a specific log time using a callback function. + +##### `DB.storeData(snID, data, updateLogTime = false)` + +Stores data in the supernode table with optional log time update. + +##### `DB.storeEdit(snID, data)` + +Edits and stores existing data in the supernode table. + +##### `DB.storeTag(snID, data)` + +Stores tagged data in the supernode table. + +##### `DB.storeNote(snID, data)` + +Stores noted data in the supernode table. + +##### `DB.deleteData(snID, vectorClock)` + +Deletes data from the supernode table. + +#### Data Clearing + +##### `DB.clearAuthorisedAppData(snID, app, adminID, subAdmins, timestamp)` + +Clears authorized app data based on specified criteria. + +##### `DB.clearUnauthorisedAppData(snID, authorisedAppList, timestamp)` + +Clears unauthorized app data based on specified criteria. + +### Exported Functions + +#### `init: initConnection` + +Exports the `initConnection` function for initializing database connection. + +#### `query: queryResolve` + +Exports the `queryResolve` function for executing parameterized SQL queries. + +#### `query_stream: queryStream` + +Exports the `queryStream` function for executing streaming SQL queries. + +#### `DB` + +Exports the `DB` object containing various database operations. + +### `initConnection(user, password, dbname, host = 'localhost')` + +**Parameters:** +- `user` (string): Database username. +- `password` (string): Database password. +- `dbname` (string): Database name. +- `host` (string, optional): Database host (default is 'localhost'). + +**Return Type:** +- `Promise`: Resolves with the `DB` object upon successful initialization. + +**Explanation:** +- Initializes a connection pool to the database using the provided credentials. +- Resolves with the `DB` object that contains various database operations. + +--- + +### `queryResolve(sql, values)` + +**Parameters:** +- `sql` (string): SQL query. +- `values` (array, optional): Parameterized values for the SQL query. + +**Return Type:** +- `Promise`: Resolves with the result of the executed SQL query. + +**Explanation:** +- Executes the provided SQL query with optional parameterized values. +- Resolves with the result of the executed SQL query. + +--- + +### `queryStream(sql, values, callback)` + +**Parameters:** +- `sql` (string): SQL query. +- `values` (array, optional): Parameterized values for the SQL query. +- `callback` (function, optional): Callback function to handle streamed results. + +**Return Type:** +- `Promise`: Resolves with the result of the streamed SQL query. + +**Explanation:** +- Executes a streaming SQL query with optional parameterized values. +- Resolves with the result of the streamed SQL query. + +--- + +### Base Tables + +#### `DB.createBase()` + +**Return Type:** +- `Promise`: Resolves with the result of table creation statements. + +**Explanation:** +- Creates base tables in the database if they do not already exist. + +#### `DB.setLastTx(id, n)` + +**Parameters:** +- `id` (string): ID for which the last transaction is being set. +- `n` (number): Value of the last transaction. + +**Return Type:** +- `Promise`: Resolves with the result of the SQL operation. + +**Explanation:** +- Inserts or updates the last transaction ID for a specified ID. + +#### `DB.setConfig(name, value)` + +**Parameters:** +- `name` (string): Name of the configuration setting. +- `value` (string): Value of the configuration setting. + +**Return Type:** +- `Promise`: Resolves with the result of the SQL operation. + +**Explanation:** +- Inserts or updates configuration values in the database. + +#### `DB.addSuperNode(id, pubKey, uri)` + +**Parameters:** +- `id` (string): ID of the supernode. +- `pubKey` (string): Public key of the supernode. +- `uri` (string): URI of the supernode. + +**Return Type:** +- `Promise`: Resolves with the result of the SQL operation. + +**Explanation:** +- Inserts or updates a supernode entry in the database. + +#### `DB.rmSuperNode(id)` + +**Parameters:** +- `id` (string): ID of the supernode to be removed. + +**Return Type:** +- `Promise`: Resolves with the result of the SQL operation. + +**Explanation:** +- Removes a supernode entry from the database. + +#### `DB.updateSuperNode(id, uri)` + +**Parameters:** +- `id` (string): ID of the supernode to be updated. +- `uri` (string): New URI for the supernode. + +**Return Type:** +- `Promise`: Resolves with the result of the SQL operation. + +**Explanation:** +- Updates the URI of a supernode entry in the database. + +#### `DB.setSubAdmin(appName, subAdmins)` + +**Parameters:** +- `appName` (string): Name of the application. +- `subAdmins` (array): Array of sub-admin IDs for the application. + +**Return Type:** +- `Promise`: Resolves with the result of the SQL operation. + +**Explanation:** +- Sets sub-admins for an application. + +#### `DB.setTrustedIDs(appName, trustedIDs)` + +**Parameters:** +- `appName` (string): Name of the application. +- `trustedIDs` (array): Array of trusted IDs for the application. + +**Return Type:** +- `Promise`: Resolves with the result of the SQL operation. + +**Explanation:** +- Sets trusted IDs for an application. + +#### `DB.addApp(appName, adminID)` + +**Parameters:** +- `appName` (string): Name of the application. +- `adminID` (string): ID of the admin for the application. + +**Return Type:** +- `Promise`: Resolves with the result of the SQL operation. + +**Explanation:** +- Inserts or updates an application entry in the database. + +#### `DB.rmApp(appName)` + +**Parameters:** +- `appName` (string): Name of the application to be removed. + +**Return Type:** +- `Promise`: Resolves with the result of the SQL operation. + +**Explanation:** +- Removes an application entry from the database. + +#### `DB.getBase()` + +**Return Type:** +- `Promise`: Resolves with an object containing essential data from base tables. + +**Explanation:** +- Retrieves essential data from base tables including last transactions, configuration settings, app list, sub-admins, trusted IDs, and supernodes. + +--- + +### Supernode Tables + +#### `DB.createTable(snID)` + +**Parameters:** +- `snID` (string): ID of the supernode for which the table is created. + +**Return Type:** +- `Promise`: Resolves with the result of the SQL operation. + +**Explanation:** +- Creates a table for a specific supernode in the database. + +#### `DB.dropTable(snID)` + +**Parameters:** +- `snID` (string): ID of the supernode for which the table is dropped. + +**Return Type:** +- `Promise`: Resolves with the result of the SQL operation. + +**Explanation:** +- Drops the table for a specific supernode from the database. + +#### `DB.listTable()` + +**Return Type:** +- `Promise`: Resolves with an array of supernode IDs. + +**Explanation:** +- Lists all supernode tables in the database. + +--- + +### Data Service (by client) + +#### `DB.addData(snID, data)` + +**Parameters:** +- `snID` (string): ID of the supernode. +- `data` (object): Data to be added to the supernode table. + +**Return Type:** +- `Promise`: Resolves with the added data. + +**Explanation:** +- Adds data to the supernode table. The data object should contain necessary fields according to the table structure. + +#### `DB.editData(snID, vectorClock, comment, newSign)` + +**Parameters:** +- `snID` (string): ID of the supernode. +- `vectorClock` (string): Vector clock identifying the data entry. +- `comment` (string): New comment for the data entry. +- `newSign` (string): New signature for the data entry. + +**Return Type:** +- `Promise`: Resolves with the edited data. + +**Explanation:** +- Edits existing data in the supernode table identified by the provided vector clock. Updates the comment and signature. + +#### `DB.getData(snID, vectorClock)` + +**Parameters:** +- `snID` (string): ID of the supernode. +- `vectorClock` (string): Vector clock identifying the data entry. + +**Return Type:** +- `Promise`: Resolves with the retrieved data. + +**Explanation:** +- Retrieves data from the supernode table identified by the provided vector clock. + +#### `DB.tagData(snID, vectorClock, tag, tagTime, tagKey, tagSign)` + +**Parameters:** +- `snID` (string): ID of the supernode. +- `vectorClock` (string): Vector clock identifying the data entry. +- `tag` (string): Tag for the data entry. +- `tagTime` (number): Timestamp for the tag. +- `tagKey` (string): Key for the tag. +- `tagSign` (string): Signature for the tag. + +**Return Type:** +- `Promise`: Resolves with the tagged data. + +**Explanation:** +- Tags data in the supernode table identified by the provided vector clock. Adds tag, tag time, tag key, and tag signature. + +#### `DB.noteData(snID, vectorClock, note, noteTime, noteKey, noteSign)` + +**Parameters:** +- `snID` (string): ID of the supernode. +- `vectorClock` (string): Vector clock identifying the data entry. +- `note` (string): Note for the data entry. +- `noteTime` (number): Timestamp for the note. +- `noteKey` (string): Key for the note. +- `noteSign` (string): Signature for the note. + +**Return Type:** +- `Promise`: Resolves with the noted data. + +**Explanation:** +- Adds a note to data in the supernode table identified by the provided vector clock. Adds note, note time, note key, and note signature. + +#### `DB.searchData(snID, request)` + +**Parameters:** +- `snID` (string): ID of the supernode. +- `request` (object): Search criteria including vector clocks, timestamps, application name, receiver ID, comment, type, and sender ID. + +**Return Type:** +- `Promise`: Resolves with an array of matching data entries. + +**Explanation:** +- Searches data in the supernode table based on the provided search criteria. + +### Backup Service + +#### `DB.lastLogTime(snID)` + +**Parameters:** +- `snID` (string): ID of the supernode. + +**Return Type:** +- `Promise`: Resolves with the last log time. + +**Explanation:** +- Retrieves the last log time from the supernode table. + +#### `DB.createGetLastLog(snID)` + +**Parameters:** +- `snID` (string): ID of the supernode. + +**Return Type:** +- `Promise`: Resolves with a function to get the last log time. + +**Explanation:** +- Creates a function to get the last log time for a specific supernode. + +#### `DB.readAllDataStream(snID, logtime, callback)` + +**Parameters:** +- `snID` (string): ID of the supernode. +- `logtime` (number): Log time to start reading data from. +- `callback` (function): Callback function to handle streamed results. + +**Return Type:** +- `Promise`: Resolves with the result of the streamed data. + +**Explanation:** +- Reads all data from a specific log time using a callback function. + +#### `DB.storeData(snID, data, updateLogTime = false)` + +**Parameters:** +- `snID` (string): ID of the supernode. +- `data` (object): Data to be stored in the supernode table. +- `updateLogTime` (boolean, optional): Indicates whether to update the log time (default is `false`). + +**Return Type:** +- `Promise`: Resolves with the stored data. + +**Explanation:** +- Stores data in the supernode table. Optionally, updates the log time if specified. + +#### `DB.storeEdit(snID, data, vectorClock)` + +**Parameters:** +- `snID` (string): ID of the supernode. +- `data` (object): Data to be updated in the supernode table. +- `vectorClock` (string): Vector clock identifying the data entry to be updated. + +**Return Type:** +- `Promise`: Resolves with the edited data. + +**Explanation:** +- Edits existing data in the supernode table identified by the provided vector clock. Updates the data fields. + +### Error Handling + +#### `DB.handleError(err)` + +**Parameters:** +- `err` (Error): Error object. + +**Return Type:** +- `void` + +**Explanation:** +- Handles errors that occur during database operations. Logs the error for debugging purposes. + +--- + +*Note: All functions return Promises for asynchronous handling. Error handling is crucial; ensure proper handling of Promise rejections and errors for robust application behavior.* + +### Usage Snippets + +``` +const { queryResolve } = require('your-database-module'); + +// Executing SQL Query +const sqlQuery = 'SELECT * FROM users WHERE id = $1'; +const userId = 123; + +queryResolve(sqlQuery, [userId]) + .then(result => { + // Handle query result + console.log(result); + }) + .catch(error => { + // Handle query error + console.error(error); + }); + + const { queryStream } = require('your-database-module'); + +// Usage Streaming SQL Query +const sqlQuery = 'SELECT * FROM large_table'; +const processData = row => { + // Process each row of data + console.log(row); +}; + +queryStream(sqlQuery, [], processData) + .then(() => { + // Streaming query completed + console.log('Streaming query completed.'); + }) + .catch(error => { + // Handle streaming query error + console.error(error); + }); + + +const { DB } = require('your-database-module'); + +// Usage : Creating base tables +DB.createBase() + .then(result => { + // Base tables created successfully + console.log(result); + }) + .catch(error => { + // Handle error during table creation + console.error(error); + }); + + +``` \ No newline at end of file diff --git a/docs/intra.md b/docs/intra.md new file mode 100644 index 0000000..d63b6c5 --- /dev/null +++ b/docs/intra.md @@ -0,0 +1,526 @@ +### Connecting to Node WebSocket + +The JavaScript function `connectToNode(snID)` establishes a WebSocket connection to a specified supernode identified by its `snID`. This function facilitates real-time communication between the server and the selected supernode, enabling the exchange of data, requests, and notifications. Here's how the function operates: + +#### Process Flow: +- **Supernode Verification:** The function first checks if the provided `snID` exists in the `floGlobals.supernodes` data structure. If the specified `snID` is not found, the function rejects with an error message indicating that the supernode is not recognized. +- **WebSocket Initialization:** If the `snID` is valid, the function initializes a new WebSocket connection using the supernode's URI obtained from `floGlobals.supernodes[snID].uri`. +- **Error Handling:** The function sets up an error event listener on the WebSocket connection. If any error occurs during the connection process, the function rejects with an error message indicating that the specified supernode is offline. +- **Connection Establishment:** Upon successful connection (`'open'` event), the function resolves with the established WebSocket instance, enabling further communication with the supernode. + +#### Impact and Communication: +- The function serves as the entry point for establishing secure and reliable communication channels with specific supernodes within the network. +- By initiating WebSocket connections to supernodes, the function enables the server to send requests, receive responses, and exchange real-time data with individual nodes, ensuring efficient coordination and synchronization of network activities. +- The function's ability to handle errors ensures robust error recovery, allowing the server to gracefully handle situations where a specified supernode is unavailable or experiences connectivity issues. +- Through this function, the server gains the capability to interact seamlessly with supernodes, enabling the execution of distributed tasks, data synchronization, and real-time event handling, essential for the smooth operation of decentralized applications and services. +- This foundational communication mechanism forms the basis for implementing advanced features such as real-time data updates, decentralized task processing, and collaborative functionalities, enhancing the overall user experience and system responsiveness. + + +### Connecting to Active Node WebSocket + +The JavaScript function `connectToActiveNode(snID, reverse = false)` is designed to establish a WebSocket connection with an active supernode in the network. It ensures that the selected supernode is online and available for communication. This function is particularly crucial for maintaining a continuous and reliable connection to the network, even in cases where the initially specified supernode is offline or unreachable. Here's how the function operates: + +#### Process Flow: +- **Supernode Verification:** The function begins by checking if the provided `snID` exists in the `floGlobals.supernodes` data structure. If the specified `snID` is not found, the function rejects with an error message indicating that the supernode is not recognized. +- **Circular Network Handling:** The function includes a check to prevent circular connections. If the specified `snID` matches the current node's ID (`keys.node_id`), the function rejects with an error message indicating that the end of the network circle has been reached. This ensures that the function does not enter an infinite loop trying to connect to itself. +- **Connection Attempt:** The function attempts to connect to the specified supernode using the `connectToNode(snID)` function. If the connection is successful, the function resolves with the established WebSocket instance, enabling further communication with the supernode. +- **Fallback to Next Node:** If the connection attempt fails (indicating that the supernode is offline), the function calculates the next node in the network circle. The direction of network traversal is determined by the `reverse` parameter. If `reverse` is `true`, the function looks for the previous node; otherwise, it looks for the next node. The function then recursively calls itself with the next node, attempting to establish a connection. +- **Recursive Retry:** The function continues attempting to connect to the next available node until a successful connection is established. If all nodes are offline or unreachable, the recursion naturally ends when there are no more nodes to attempt. + +#### Impact and Network Resilience: +- This function ensures that the server always maintains an active and reliable connection to the network by continuously seeking out available supernodes. +- By handling circular network scenarios and gracefully falling back to adjacent nodes, the function enhances the network's resilience. It allows the server to adapt dynamically to changing network conditions, ensuring uninterrupted communication channels. +- The recursive nature of the function ensures persistent attempts to establish connections, making it an integral part of the system's self-healing mechanism. It allows the server to autonomously recover from temporary network disruptions and resume normal operations once an active node is found. +- This function's ability to navigate the network intelligently and select appropriate nodes for connection contributes significantly to the overall robustness of decentralized applications. It ensures that users experience minimal downtime and latency, even in challenging network environments, providing a seamless and responsive user experience. +- The function's design promotes decentralized decision-making, enabling the server to adapt dynamically to network topology changes without manual intervention. This autonomous behavior aligns with the principles of decentralization, ensuring that the system can continue functioning effectively in the absence of centralized control. + + +### Connecting to Next Available Node WebSocket + +The JavaScript function `connectToNextNode(curNode = keys.node_id)` is responsible for establishing a WebSocket connection with the next available supernode in the network. This function ensures continuous and reliable communication channels by connecting to the immediate neighboring node in the network circle. Here's a breakdown of how the function works: + +#### Process Flow: +- **Supernode Verification:** The function begins by checking if the provided `curNode` ID exists in the `floGlobals.supernodes` data structure. If `curNode` matches the server's own node ID (`keys.node_id`), it ensures that the server itself is a supernode. If not, the function rejects with an error message indicating that the server is not recognized as a supernode. +- **Finding the Next Node:** Using the `cloud.nextNode(curNode)` function, the next node ID in the network circle is calculated. If the next node is the server itself (`keys.node_id`), it indicates that no other node is online, and the function rejects with a message indicating the absence of other online nodes. +- **Connection Attempt:** The function attempts to establish a WebSocket connection with the identified next node using the `connectToNode(nextNodeID)` function. If the connection is successful, the function resolves, indicating that the connection has been established. +- **Backup Handshake Initiation:** Upon successful connection, the function sends a specific packet type (`TYPE_.BACKUP_HANDSHAKE_INIT`) to initiate a backup handshake process with the next node. This step ensures that the server establishes a backup communication channel with the neighboring node, enhancing network redundancy and fault tolerance. +- **Recursive Retry:** If the connection attempt fails (indicating that the next node is offline), the function recursively calls itself with the next node ID, attempting to connect to the subsequent node. This recursive retry mechanism continues until a successful connection is established or until there are no more nodes to attempt. +- **Resolution:** If a connection is established and the backup handshake initiation is successful, the function resolves with a message indicating the successful initiation of the backup handshake process. + +#### Importance and Redundancy Enhancement: +- This function plays a vital role in ensuring network redundancy by establishing a backup communication channel with the next available node in the network circle. By having multiple active connections to neighboring nodes, the server enhances its fault tolerance and resilience against network disruptions. +- The recursive nature of the function allows the server to adapt dynamically to changing network conditions. If a neighboring node becomes unavailable, the server automatically redirects its connection attempts to the subsequent node, ensuring that the server is always connected to an active node whenever possible. +- The initiation of the backup handshake (`TYPE_.BACKUP_HANDSHAKE_INIT`) is a proactive measure that enables the server to establish backup channels preemptively. By initiating the handshake, the server ensures that the backup connection is fully operational and ready to seamlessly take over in case of the primary connection's failure. +- This function's ability to autonomously establish backup connections with neighboring nodes demonstrates the server's self-healing capabilities. It allows the server to recover from connection failures without manual intervention, ensuring uninterrupted service for users and applications relying on the server's network connectivity. +- Overall, this function significantly contributes to the server's reliability and availability. It ensures that the server can continue functioning even if individual nodes experience temporary outages or network disturbances, providing a robust and dependable infrastructure for decentralized applications. + + +### Connecting to Alive Nodes in the Network + +The JavaScript function `connectToAliveNodes(nodes = null)` is designed to establish WebSocket connections with a specified list of nodes in the network. This function ensures that the server connects to multiple nodes simultaneously, enabling efficient communication and data exchange within the network. Here's a breakdown of how the function operates: + +#### Process Flow: +- **Nodes Validation:** If the `nodes` parameter is not provided or is not an array, the function defaults to connecting with all available supernodes except for the server's own node (`keys.node_id`). It filters out the server's own node ID from the list of nodes to prevent attempting a connection to itself. +- **Parallel Connection Attempt:** The function uses the `Promise.allSettled` method to initiate parallel connection attempts to all nodes in the filtered list. Each connection attempt is performed using the `connectToNode(n)` function, where `n` represents a node ID from the list. +- **Connection Status Analysis:** The results of the connection attempts are processed asynchronously. For each node, the function checks the status of the connection attempt. If a connection is successfully established (`status === "fulfilled"`), the corresponding WebSocket instance is stored in the `ws_connections` object with the node ID as the key. If the connection attempt fails (`status === "rejected"`), the corresponding entry in the `ws_connections` object is set to `null`. +- **Resolution:** After processing all connection attempts and storing the WebSocket instances or `null` values in the `ws_connections` object, the function resolves with this object. The resolved value represents a mapping between node IDs and their corresponding WebSocket connections (or `null` for unsuccessful connections). +- **Connection Redundancy:** By attempting connections to multiple nodes in parallel, the function enhances network redundancy. Even if some connection attempts fail, the server can establish connections with the nodes that are online, ensuring continuous communication channels within the network. +- **Dynamic Node Configuration:** The ability to specify a custom list of nodes allows for flexibility in network configuration. Server operators can choose specific nodes to connect to based on factors such as geographic location, network performance, or other criteria, tailoring the server's connections to meet specific requirements. +- **Fault Tolerance:** In case any node experiences temporary outages or connection issues, the function's parallel connection approach ensures that the server can quickly identify and establish connections with other available nodes. This fault tolerance mechanism enhances the server's overall reliability and resilience against network disruptions. + +Overall, the `connectToAliveNodes` function contributes to the server's robust network architecture by enabling efficient, parallel connections to multiple nodes. This approach enhances the server's ability to maintain stable and responsive communication links with the broader network, supporting seamless interactions with decentralized applications and users. + + +### Connecting to All Active Nodes in the Network + +The JavaScript function `connectToAllActiveNodes(nodes = null)` facilitates establishing WebSocket connections with active nodes in the network. This function allows the server to connect to nodes that are currently online, enhancing the server's ability to maintain real-time communication channels. Here's how the function operates: + +#### Process Flow: +- **Nodes Validation:** If the `nodes` parameter is not provided or is not an array, the function defaults to attempting connections with all available supernodes except for the server's own node (`keys.node_id`). It ensures that the server does not attempt to connect to itself by filtering out the server's own node ID from the list of nodes. +- **Parallel Active Node Connection:** The function utilizes the `Promise.allSettled` method to initiate parallel connection attempts to all nodes in the filtered list. Each connection attempt is performed using the `connectToActiveNode(n)` function, where `n` represents a node ID from the list of active nodes. +- **Connection Status Analysis:** The results of the connection attempts are processed asynchronously. For each node, the function checks the status of the connection attempt. If a connection is successfully established (`status === "fulfilled"`), the corresponding WebSocket instance is stored in the `ws_connections` object with the node ID as the key. If the connection attempt fails (`status === "rejected"`), the corresponding entry in the `ws_connections` object is set to `null`. +- **Resolution:** After processing all connection attempts and storing the WebSocket instances or `null` values in the `ws_connections` object, the function resolves with this object. The resolved value represents a mapping between node IDs and their corresponding WebSocket connections (or `null` for unsuccessful connections). +- **Enhanced Network Connectivity:** By connecting to all active nodes in parallel, the function optimizes the server's network connectivity. This parallel connection approach ensures that the server can quickly establish connections with multiple online nodes, maximizing the server's ability to exchange real-time data with the network. +- **Network Robustness:** The ability to connect to all active nodes enhances the server's robustness. If any specific node experiences temporary outages or connection issues, the server can rely on connections with other active nodes, ensuring continuous communication channels and minimizing potential disruptions in network interactions. +- **Dynamic Node Configuration:** The option to specify a custom list of nodes allows for flexibility in network configuration. Server operators can tailor the server's connections to specific nodes based on various criteria, ensuring that the server communicates with nodes that align with specific requirements, such as geographic location or network performance. + +In summary, the `connectToAllActiveNodes` function contributes to the server's network reliability and responsiveness by enabling efficient, parallel connections to all active nodes in the network. This approach enhances the server's ability to participate in real-time communication, supporting seamless interactions with decentralized applications, users, and other network components. + + +### Processing Tasks from Next Node + +The JavaScript function `processTaskFromNextNode(packet)` plays a vital role in handling various tasks received from the next node in the network. These tasks are communicated via packets and contain specific instructions that the server must interpret and act upon. Here's how the function operates: + +#### Task Processing Flow: +- **Packet Parsing:** The function starts by parsing the incoming `packet` to extract essential information, such as the sender's ID (`from`) and an array of `message` objects, each representing a specific task. +- **Task Switching:** The function iterates through the `message` array and evaluates the `type_` property of each task to determine the nature of the instruction. +- **Task Handling:** Based on the task type, the function performs different actions: + - **RECONNECT_NEXT_NODE:** When a node in between becomes available, the function triggers the `reconnectNextNode()` action. This action likely involves reestablishing connections and synchronizing data with the reconnected node. + - **BACKUP_HANDSHAKE_END:** The `handshakeEnd()` action is triggered, indicating the completion of a backup handshake process. + - **REQ_HASH:** The server sends block hashes to the specified node (`task.node_i`) using the `sync.sendBlockHashes` function, likely as part of a data synchronization process. + - **RES_HASH:** The server checks the integrity of received block hashes from the specified node (`task.node_i`) using the `sync.checkBlockHash` function. This validation ensures the consistency and authenticity of the received data. + - **VAL_LAST_BLK:** The server sets the last block information for the specified node (`task.node_i`) using the `sync.setLastBlock` function, indicating the latest synchronized block number. + - **REQ_BLOCK:** The server sends specific block data to the specified node (`task.node_i`, `task.block_n`) using the `sync.sendBlockData` function, likely for data retrieval or synchronization purposes. + - **INDICATE_BLK:** The server processes a block synchronization indicator from the specified node (`task.node_i`, `task.block_n`, `task.status`, `from`) using the `sync.syncIndicator` function. This action involves interpreting the synchronization status and potentially taking corrective measures. + - **STORE_BACKUP_DATA:** The server stores backup data (`task.data`) received from the specified node (`from`) using the `storeBackupData` function. This task likely involves handling critical backup information to ensure data redundancy and recovery capabilities. + - **Invalid Task Type:** If the task type does not match any of the predefined cases, the function issues a warning, indicating that an unrecognized task type was received from the next node. + +#### Logging and Debugging: +- **Debug Output:** The function outputs debug information (`_nextNode: `, `packet`) to provide insight into the received packet and its contents. This logging helps in monitoring and troubleshooting the communication flow between nodes. +- **Warning for Invalid Tasks:** If the function encounters a task with an unrecognized or invalid type, it logs a warning message (`Invalid task type_: ...`) to alert developers and operators about unexpected or unsupported task types. + +#### Task-Based Network Management: +- **Dynamic Task Handling:** The function's ability to handle diverse task types enables dynamic network management. By interpreting different tasks, the server can adapt to changing network conditions, synchronize data, perform backups, and respond to various events triggered by neighboring nodes. +- **Network Robustness:** The server's capability to process a wide range of tasks enhances the network's robustness. The server can efficiently handle task-based instructions from adjacent nodes, ensuring smooth operation even in complex network scenarios. +- **Task Extensibility:** The function can be extended to handle additional task types in the future. This extensibility ensures that the server remains adaptable to evolving network requirements and can incorporate new functionalities as the network architecture evolves. + +In summary, the `processTaskFromNextNode` function serves as a critical component in the server's communication and coordination with neighboring nodes. Its ability to interpret diverse tasks, manage network events, and handle unexpected scenarios makes it a key element in maintaining a resilient, responsive, and adaptable network infrastructure. + + +### Processing Tasks from Previous Node + +The JavaScript function `processTaskFromPrevNode(packet)` is responsible for handling various tasks received from the previous node in the network. Similar to `processTaskFromNextNode(packet)`, this function interprets tasks encapsulated within packets and executes corresponding actions. Here's how the function operates: + +#### Task Processing Flow: +- **Packet Parsing:** The function begins by parsing the incoming `packet` to extract essential information, including the sender's ID (`from`) and an array of `message` objects, each representing a specific task. +- **Task Switching:** The function iterates through the `message` array and evaluates the `type_` property of each task to identify the nature of the instruction. +- **Task Handling:** Based on the task type, the function performs different actions: + - **ORDER_BACKUP:** The function initiates the `orderBackup(task.order)` action, indicating the need to create a backup of specific data (`task.order`). This task likely involves organizing and prioritizing data for backup purposes. + - **STORE_BACKUP_DATA:** The server stores backup data (`task.data`) received from the previous node (`from`) using the `storeBackupData` function. This task ensures that backup data is safely retained for redundancy and recovery. + - **EDIT_BACKUP_DATA:** The server processes an edit operation on backup data (`task.data`) received from the previous node (`from`) using the `editBackupData` function. This task likely involves updating existing backup records to reflect changes made to the original data. + - **TAG_BACKUP_DATA:** The server handles a tagging operation on backup data (`task.data`) received from the previous node (`from`) using the `tagBackupData` function. This task likely involves categorizing backup data for organizational purposes. + - **NOTE_BACKUP_DATA:** The server manages a note operation on backup data (`task.data`) received from the previous node (`from`) using the `noteBackupData` function. This task likely involves attaching additional notes or metadata to backup records. + - **REQ_HASH:** The server sends block hashes to the specified node (`task.node_i`) using the `sync.sendBlockHashes` function, likely as part of a data synchronization process. + - **RES_HASH:** The server checks the integrity of received block hashes from the specified node (`task.node_i`) using the `sync.checkBlockHash` function. This validation ensures the consistency and authenticity of the received data. + - **VAL_LAST_BLK:** The server sets the last block information for the specified node (`task.node_i`) using the `sync.setLastBlock` function, indicating the latest synchronized block number. + - **REQ_BLOCK:** The server sends specific block data to the specified node (`task.node_i`, `task.block_n`) using the `sync.sendBlockData` function, likely for data retrieval or synchronization purposes. + - **INDICATE_BLK:** The server processes a block synchronization indicator from the specified node (`task.node_i`, `task.block_n`, `task.status`, `from`) using the `sync.syncIndicator` function. This action involves interpreting the synchronization status and potentially taking corrective measures. + - **DELETE_MIGRATED_DATA:** The server handles a request to delete migrated data (`task.data`) received from the previous node (`from`) using the `deleteMigratedData` function. This task likely involves removing data that has been successfully migrated to its destination. + +#### Logging and Debugging: +- **Debug Output:** The function outputs debug information (`_prevNode: `, `packet`) to provide insight into the received packet and its contents. This logging helps in monitoring and troubleshooting the communication flow between nodes. +- **Warning for Invalid Tasks:** If the function encounters a task with an unrecognized or invalid type, it logs a warning message (`Invalid task type_: ...`) to alert developers and operators about unexpected or unsupported task types. + +#### Task-Based Data Management: +- **Backup Operations:** The function handles backup-related tasks, ensuring the proper organization, storage, and maintenance of backup data. This is crucial for data redundancy and disaster recovery. +- **Data Synchronization:** Tasks related to block hashes, block data, and synchronization indicators enable efficient data synchronization between nodes. This synchronization is essential for maintaining a consistent view of the blockchain across the network. +- **Data Integrity:** Tasks such as hash validation (`RES_HASH`) and synchronization indicators (`INDICATE_BLK`) contribute to verifying data integrity, allowing nodes to identify and resolve discrepancies in the shared dataset. + +In summary, the `processTaskFromPrevNode` function plays a vital role in managing backup operations, data synchronization, and data integrity verification within the network. Its ability to handle diverse tasks from the previous node ensures the reliability, consistency, and security of the shared blockchain data. + + +### Processing Tasks from Supernodes + +The JavaScript function `processTaskFromSupernode(packet, ws)` is responsible for handling various tasks received from any supernode in the network. These tasks are encapsulated within packets and are processed to execute corresponding actions. Here's how the function operates: + +#### Task Processing Flow: +- **Packet Parsing:** The function begins by parsing the incoming `packet` to extract essential information, including the sender's ID (`from`) and an array of `message` objects, each representing a specific task. +- **Task Switching:** The function iterates through the `message` array and evaluates the `type_` property of each task to identify the nature of the instruction. +- **Task Handling:** Based on the task type, the function performs different actions: + - **BACKUP_HANDSHAKE_INIT:** The function initiates the `handshakeMid(from, ws)` action, indicating the beginning of a handshake process with the supernode specified by `from`. Handshakes are critical for establishing secure and authenticated communication channels between nodes. + - **STORE_MIGRATED_DATA:** The server stores migrated data (`task.data`) received from the supernode. This task likely involves managing data that has been moved or transferred between nodes, ensuring its safe storage and accessibility. + - **INITIATE_REFRESH:** The function triggers the `initiateRefresh()` action, which likely involves initiating a refresh process within the network. Refresh operations could include updating cached data, re-synchronizing with other nodes, or performing maintenance tasks to ensure data consistency. + +#### Logging and Debugging: +- **Debug Output:** The function outputs debug information (`superNode: `, `packet`) to provide insight into the received packet and its contents. This logging helps in monitoring and troubleshooting the communication flow between supernodes. +- **Warning for Invalid Tasks:** If the function encounters a task with an unrecognized or invalid type, it logs a warning message (`Invalid task type_: ...`) to alert developers and operators about unexpected or unsupported task types. + +#### Secure Communication Establishment: +- **Handshake Initialization:** The function handles the initiation of handshake processes (`BACKUP_HANDSHAKE_INIT`), which are crucial for establishing secure communication channels. Handshakes typically involve cryptographic validation and exchange of keys to ensure the authenticity and integrity of transmitted data. + +#### Data Management and Network Maintenance: +- **Data Migration:** Tasks related to migrating data between nodes (`STORE_MIGRATED_DATA`) indicate the seamless transfer of information within the network. Proper management of migrated data is essential to prevent data loss and maintain a consistent dataset across nodes. +- **Network Refresh:** The `INITIATE_REFRESH` task suggests network-wide refreshing operations. Such operations are fundamental for maintaining the health and synchronization of the blockchain network, ensuring that all nodes have up-to-date and accurate information. + +In summary, the `processTaskFromSupernode` function plays a central role in managing secure communication, data migration, and network maintenance within the blockchain network. Its ability to handle diverse tasks from supernodes ensures the reliability, security, and efficiency of inter-node communication and data management. + + +### Handshake Acknowledgment and Network Reconfiguration + +The JavaScript function `handshakeMid(id, ws)` plays a critical role in acknowledging and handling handshakes with adjacent nodes in the blockchain network. This function is pivotal for ensuring secure communication, proper node ordering, and synchronization of data. Let's delve into the function's workflow: + +#### Handshake Acknowledgment: +- **Handshake Verification:** The function verifies the incoming node's ID (`id`) and WebSocket connection (`ws`) against the previous node (`_prevNode.id`). This verification ensures that the handshake request comes from an appropriate node in the network. +- **Previous Node Existence:** If a previous node is already configured (`_prevNode.id` exists), the function checks if the incoming node is correctly positioned in the network. If the incoming node is in the correct order, the existing connection with the previous node is closed, and the new connection is established. +- **Handshake Closure and Reconfiguration:** If the handshake is successful, the function sends a message to close the previous node's connection (`RECONNECT_NEXT_NODE`) and sets up the new connection. Additionally, a handshake completion message (`BACKUP_HANDSHAKE_END`) is sent to the new node to finalize the handshake process. + +#### Network Reconfiguration and Synchronization: +- **Next Node Reconnection:** If the next node is not configured (`!_nextNode.id`), the function triggers the reconnection process (`reconnectNextNode()`) to establish a connection with the subsequent node in the network. +- **Node Ordering and Synchronization:** The function reconfigures the node order based on the incoming node's position. It identifies nodes that need data synchronization (`req_sync`) and nodes with updated order (`new_order`). Synchronization requests are sent for nodes requiring data synchronization, and updated node order is transmitted to ensure consistency across nodes. + +#### Handling Node Order and Data Synchronization: +- **Node Reordering:** Nodes are reordered based on their synchronization status and position in the network. Proper ordering is crucial for maintaining the integrity and continuity of the blockchain. +- **Data Synchronization:** Nodes requiring data synchronization (`req_sync`) are identified and sent synchronization requests. This step ensures that nodes have consistent and up-to-date data, enhancing the blockchain's reliability. + +In summary, the `handshakeMid` function serves as a key component in the blockchain network's configuration and synchronization processes. Its ability to acknowledge handshakes, reconfigure node connections, and manage data synchronization ensures the seamless operation and consistency of the network. Proper handshakes and synchronization are vital for maintaining a robust and secure blockchain ecosystem. + + +### Handshake Completion and Node Configuration + +The JavaScript function `handshakeEnd()` plays a pivotal role in completing the handshake process with the next node in the blockchain network. This function is crucial for establishing a secure and synchronized connection, ensuring proper data transmission and network integrity. Let's explore the function's workflow and significance: + +#### Handshake Completion and Network Configuration: +- **Handshake Confirmation:** Upon successful completion of the handshake with the next node, the function logs a message indicating the successful backup node connection. This confirmation verifies that the backup node (`_nextNode.id`) has been successfully established, providing essential feedback to the network operators. +- **Node Order Transmission:** After the handshake is confirmed, the function constructs a packet (`ORDER_BACKUP`) containing the updated node order (`_list.get()`). This packet encapsulates the ordered list of nodes in the network, ensuring that all nodes have consistent information about the network structure. +- **Packet Transmission:** The constructed packet is sent to the next node (`_nextNode.send(...)`) as part of the handshake completion process. Transmitting the node order is crucial for maintaining a synchronized and consistent view of the network across all nodes. +- **Network Integrity:** By transmitting the node order, the function contributes to preserving the integrity of the blockchain network. Consistent node ordering is essential for ensuring that data propagation, validation, and synchronization occur uniformly across the network. + +#### Significance of Handshake Completion: +- **Data Consistency:** Completing the handshake by transmitting the node order guarantees that all nodes have a coherent understanding of the network structure. This consistency is vital for validating transactions, managing data, and maintaining the blockchain's integrity. +- **Network Reliability:** A successfully completed handshake signifies a reliable connection between nodes. Reliability is paramount for secure data transmission, backup management, and ensuring that the network operates smoothly under various conditions. +- **Operational Confidence:** Network operators and administrators gain confidence in the blockchain's operational status when a handshake is successfully completed. This confidence stems from the assurance of a stable and synchronized network configuration. + +In summary, the `handshakeEnd()` function is instrumental in finalizing the handshake process with the next node in the blockchain network. Its role in confirming the connection, transmitting the node order, and ensuring network integrity is essential for establishing a robust, consistent, and reliable blockchain ecosystem. + + +### Node Reconnection Strategy: Reconnect to Next Available Node + +The JavaScript function `reconnectNextNode()` outlines a strategic approach for re-establishing a connection to the next available node in the blockchain network. This function is pivotal for ensuring continuous network operation, fault tolerance, and data integrity. Let's delve into the function's workflow and the significance of its implementation: + +#### Node Reconnection Process: +- **Previous Node Closure:** Before initiating the reconnection process, the function first closes the existing connection to the next node (`_nextNode.close()`). This step is essential to ensure a clean and unobstructed transition to the new connection. +- **Connection Attempt:** The function then calls the `connectToNextNode()` function, which attempts to establish a connection with the next available node in the network. This connection attempt is asynchronous and operates based on the network's current status. +- **Handling Connection Results:** Upon the completion of the connection attempt, the function processes the results. If the reconnection is successful, it logs the result for debugging and informational purposes (`console.debug(result)`). Conversely, if the reconnection fails due to the absence of online nodes, the function initiates the following actions: + - **Logging and Notification:** The function logs an informational message indicating the absence of online nodes (`console.info(error)`). This notification provides valuable insights into the network's current state to network operators and administrators. + - **Previous Node Closure (Fallback):** If the previous node (`_prevNode.id`) is still active, the function closes the connection to the previous node as a fallback strategy. Closing inactive connections helps maintain network cleanliness and prevents potential issues. + - **Node Table Creation:** The function iterates through all supernodes (`floGlobals.supernodes`) and creates tables for each node in the blockchain database (`DB.createTable(sn)`). Table creation is vital for managing data storage and retrieval in a structured manner. + - **Node List Reset:** For each supernode, the function resets the corresponding node's status in the node list (`_list[sn] = 0`). Resetting the status ensures that nodes are marked as available for connections and data synchronization. + +#### Significance of Reconnection Strategy: +- **Network Continuity:** The function's reconnection strategy ensures the continuous operation of the blockchain network even in the face of node failures or disconnections. Seamless reconnection mechanisms are essential for preventing network disruptions and maintaining uninterrupted data flow. +- **Fallback Mechanism:** The function's ability to close inactive connections (`_prevNode.id`) acts as a fallback mechanism. This proactive approach to connection management enhances the network's reliability and stability by preventing lingering, inactive connections. +- **Database Management:** By creating tables for each supernode, the function contributes to efficient database management. Structured data storage facilitates organized data handling, enabling seamless querying and retrieval operations. + +In summary, `reconnectNextNode()` exemplifies a robust node reconnection strategy that combines connection closure, connection attempts, and fallback mechanisms. Its role in ensuring network continuity, managing active connections, and initiating database preparations underscores its significance in maintaining a resilient and operational blockchain ecosystem. + + +### Backup Data Ordering: Optimizing Stored Backup Order + +The JavaScript function `orderBackup(order)` encapsulates a critical aspect of data management within the blockchain network: the ordering of stored backup data. This function orchestrates the reorganization of stored backup data based on specified order information (`order`). Through a meticulous process, the function ensures that backup data is strategically organized and aligned with the network's requirements. Let's delve into the function's workflow and explore the key aspects of its implementation: + +#### Data Reordering Process: +- **Ordering Criteria:** The function receives an `order` object, which contains ordering information for various nodes within the network. Each node's order reflects the depth of its backup data storage. Nodes that exceed the configured backup depth are subject to specific actions to optimize data storage. +- **Current Serving Nodes:** The function retrieves the list of nodes currently being served (`cur_serve`), including inner nodes of the previous node (`_prevNode.id`) and the current node (`keys.node_id`). This information is crucial for identifying nodes that need synchronization and reordering. +- **Iterative Evaluation:** The function iterates through the provided `order` object, evaluating each node's backup depth and its alignment with the network's configuration. +- **Data Cleanup and Synchronization:** + - Nodes exceeding the backup depth (`order[n] >= floGlobals.sn_config.backupDepth`) undergo data cleanup. The function initiates the removal of excess backup data for these nodes, safeguarding storage resources and maintaining optimal data management. + - Nodes within the acceptable backup depth range (`order[n] >= 0`) are subject to reordering and potential synchronization. For nodes requiring synchronization (`_list[n] === undefined`), the function marks them for data synchronization (`req_sync.push(n)`). + - For nodes within the acceptable backup depth, the function updates their order (`_list[n] = order[n] + 1`) in the backup data storage list (`_list`). The updated order reflects the next available storage slot for backup data. +- **Synchronization Request:** Nodes requiring synchronization (`req_sync`) trigger data synchronization requests to the previous node (`_prevNode`) to ensure consistent data across the network. +- **Order Transmission:** The function constructs a new order object (`_list.get(synced_list)`) containing the synchronized nodes (`synced_list`). This new order is transmitted to the next node (`_nextNode`) to align backup data storage across network nodes. +- **Optimized Data Storage:** By aligning backup data storage with the network's configuration and depth settings, the function optimizes data storage resources. This alignment ensures that backup data is maintained efficiently while adhering to the specified backup depth for each node. + +#### Significance of Data Ordering: +- **Resource Management:** Effective data ordering optimizes storage resources by removing excess data and synchronizing nodes strategically. This resource optimization is crucial for maintaining storage efficiency and preventing data overload. +- **Consistent Data:** Data synchronization requests and order transmissions ensure consistent data across network nodes. Consistency is vital for preserving the integrity of the blockchain and enabling seamless data access and retrieval. +- **Network Performance:** Optimized data storage enhances network performance by reducing unnecessary data transfers and aligning backup data with the network's operational requirements. This streamlined approach contributes to smoother data transactions and interactions within the network. + +In summary, `orderBackup(order)` stands as a pivotal function in the blockchain network's data management strategy. By orchestrating the reordering of backup data based on specific criteria, the function ensures resource efficiency, data consistency, and enhanced network performance. Its role in aligning data storage with the network's operational parameters underscores its significance in maintaining a robust and optimized blockchain ecosystem. + + +### Data Backup and Storage: Ensuring Data Redundancy and Availability + +The JavaScript function `storeBackupData(data, from, packet)` plays a fundamental role in the blockchain network's data redundancy and availability strategy. This function is responsible for storing backup data received from other network nodes, ensuring that critical data is redundantly stored across multiple nodes. Let's explore the key aspects of this function and its significance in the context of blockchain data management: + +#### Core Functionality: +- **Data Reception:** The function receives `data` representing the backup data to be stored. Additionally, it receives `from`, denoting the source node sending the data, and `packet`, encapsulating the data transmission packet. +- **Closest Node Determination:** The function identifies the closest node (`closestNode`) to the intended receiver of the backup data (`data.receiverID`). This determination is crucial for directing the data to the most relevant storage location within the network. +- **Data Storage Verification:** The function checks whether the `closestNode` is included in the list of stored nodes (`_list.stored`). If the node is a designated storage location, the backup data is stored in the corresponding database using the `DB.storeData(closestNode, data)` operation. This step ensures that the backup data is securely stored in the appropriate node's database. +- **Backup Depth Check:** The function evaluates the current backup depth (`_list[closestNode]`) of the `closestNode`. If the backup depth is below the configured threshold (`floGlobals.sn_config.backupDepth`) and the source node (`_nextNode.id`) is not the same as the sender (`from`), the function initiates the transmission of the data packet to the next node (`_nextNode.send(packet)`). This step enhances data redundancy by ensuring that backup data is propagated to the subsequent node in the network, reinforcing data availability and reliability. + +#### Importance of Redundant Data Storage: +- **Data Resilience:** Storing backup data across multiple nodes enhances the network's resilience. Redundant data storage ensures that even if a node experiences issues or downtime, data can be retrieved from alternative storage locations, preserving the blockchain's integrity. +- **High Availability:** Redundant data storage increases data availability. If a user or application needs access to specific data, the blockchain network can retrieve the required information from multiple redundant sources, ensuring uninterrupted service and responsiveness. +- **Data Integrity:** Redundant data storage safeguards data integrity. By maintaining multiple copies of critical data, the blockchain network can validate and cross-verify information, minimizing the risk of data corruption or tampering. + +In summary, `storeBackupData(data, from, packet)` embodies a key aspect of blockchain data management by facilitating redundant data storage. Its role in directing backup data to appropriate nodes, verifying storage eligibility, and initiating data propagation enhances the network's robustness, availability, and data integrity. This function significantly contributes to the blockchain's ability to withstand challenges, deliver consistent service, and maintain the integrity of its stored information. + + +### Data Backup and Editing: Ensuring Immutable Blockchain Records + +The JavaScript function `editBackupData(data, from, packet)` plays a pivotal role in the blockchain network's data integrity and immutability. This function is responsible for handling the editing of backup data, ensuring that modifications to existing records adhere to the network's rules and policies. Let's explore the key aspects of this function and its significance in maintaining the blockchain's immutable nature: + +#### Core Functionality: +- **Data Reception:** The function receives `data`, representing the edited data to be stored. Additionally, it receives `from`, denoting the source node initiating the edit, and `packet`, encapsulating the data transmission packet. +- **Closest Node Determination:** The function identifies the closest node (`closestNode`) to the intended receiver of the edited data (`data.receiverID`). This determination is crucial for directing the edited data to the most relevant storage location within the network. +- **Edit Verification:** The function checks whether the `closestNode` is included in the list of stored nodes (`_list.stored`). If the node is a designated storage location, the edited data is stored in the corresponding database using the `DB.storeEdit(closestNode, data)` operation. This step ensures that the edited data is securely stored while preserving the blockchain's historical record. +- **Backup Depth Check:** The function evaluates the current backup depth (`_list[closestNode]`) of the `closestNode`. If the backup depth is below the configured threshold (`floGlobals.sn_config.backupDepth`) and the source node (`_nextNode.id`) is not the same as the sender (`from`), the function initiates the transmission of the data packet to the next node (`_nextNode.send(packet)`). This step ensures that the edited data is propagated to the subsequent node in the network, maintaining a consistent blockchain state. + +#### Importance of Immutable Blockchain Records: +- **Data Integrity:** Immutable records are essential for preserving the integrity of the blockchain. Once data is added to the blockchain, it cannot be altered or tampered with. The `editBackupData` function ensures that any edits adhere to the network's rules and are recorded transparently and securely. +- **Trustworthiness:** Immutable records enhance the trustworthiness of the blockchain. Users and applications can rely on the permanence of recorded transactions and data, fostering trust in the blockchain network's reliability and accuracy. +- **Historical Transparency:** The ability to edit data while maintaining historical transparency is a unique feature of blockchain technology. `editBackupData` captures these edits, allowing network participants to trace the evolution of specific data over time. + +In summary, `editBackupData(data, from, packet)` safeguards the blockchain's integrity and immutability by managing the editing of backup data. Its role in verifying edits, ensuring proper storage, and propagating edited data to subsequent nodes maintains the blockchain's unchangeable nature. This function reinforces the network's trustworthiness, transparency, and data integrity, key pillars of a robust and reliable blockchain ecosystem. + + +### Ensuring Data Integrity: Tagging and Backing Up Blockchain Records + +The JavaScript function `tagBackupData(data, from, packet)` is a critical component in the blockchain network, specifically dedicated to managing the tagging and backup of blockchain records. This function plays a pivotal role in maintaining data integrity, ensuring that tagged data is securely stored and backed up across the network. Let's explore the fundamental aspects of this function and its significance in preserving the reliability and consistency of the blockchain: + +#### Core Functionality: +- **Data Reception:** The function receives `data`, representing the tagged data to be stored. Additionally, it receives `from`, indicating the source node initiating the tagging, and `packet`, encapsulating the data transmission packet. +- **Closest Node Determination:** The function identifies the closest node (`closestNode`) to the intended receiver of the tagged data (`data.receiverID`). This step is essential for directing the tagged data to the most suitable storage location within the network. +- **Tagging and Storage:** The function verifies whether the `closestNode` is included in the list of stored nodes (`_list.stored`). If the node is designated as a storage location, the tagged data is stored in the corresponding database using the `DB.storeTag(closestNode, data)` operation. This ensures that the tagged data is securely archived and accessible for future reference. +- **Backup Depth Check:** The function evaluates the current backup depth (`_list[closestNode]`) of the `closestNode`. If the backup depth is below the configured threshold (`floGlobals.sn_config.backupDepth`) and the source node (`_nextNode.id`) is not the same as the sender (`from`), the function initiates the transmission of the data packet to the next node (`_nextNode.send(packet)`). This step guarantees that the tagged data is propagated to the subsequent node in the network, maintaining consistent backup copies across nodes. + +#### Importance in Data Integrity: +- **Immutable Tagging:** The function ensures that once data is tagged and stored, it remains immutable and cannot be altered. Immutable tagging preserves the integrity of tagged records, providing a reliable historical reference for all network participants. +- **Secure Storage:** Tagged data is securely stored in designated nodes, safeguarding it from unauthorized access or tampering. The secure storage of tagged data reinforces the network's reliability and trustworthiness. +- **Reliable Backup:** By initiating the backup process for tagged data, the function guarantees that backup copies are consistently maintained across nodes. Reliable backups enhance the network's resilience, allowing for seamless data recovery in case of node failures or other unforeseen events. + +In summary, `tagBackupData(data, from, packet)` is instrumental in preserving data integrity within the blockchain network. Its role in securely tagging and backing up blockchain records ensures the reliability, security, and consistency of network data. By maintaining immutable records, secure storage, and reliable backups, this function reinforces the blockchain's trustworthiness and resilience, contributing to a robust and dependable blockchain ecosystem. + + +### Preserving Data Continuity: Noting and Backing Up Blockchain Information + +The JavaScript function `noteBackupData(data, from, packet)` serves as a pivotal component in the blockchain network, specifically dedicated to managing the notation and backup of blockchain information. This function plays a crucial role in ensuring the continuous recording and secure archiving of essential data within the network. Let's delve into the key aspects of this function and its significance in maintaining the seamless flow and reliability of blockchain information: + +#### Core Functionality: +- **Data Reception:** The function receives `data`, representing the noted data to be stored. Additionally, it receives `from`, indicating the source node initiating the notation, and `packet`, encapsulating the data transmission packet. +- **Closest Node Determination:** The function identifies the closest node (`closestNode`) to the intended receiver of the noted data (`data.receiverID`). This step is essential for directing the noted data to the most suitable storage location within the network. +- **Notation and Storage:** The function verifies whether the `closestNode` is included in the list of stored nodes (`_list.stored`). If the node is designated as a storage location, the noted data is stored in the corresponding database using the `DB.storeNote(closestNode, data)` operation. This ensures that the noted data is securely archived and accessible for future reference. +- **Backup Depth Check:** The function evaluates the current backup depth (`_list[closestNode]`) of the `closestNode`. If the backup depth is below the configured threshold (`floGlobals.sn_config.backupDepth`) and the source node (`_nextNode.id`) is not the same as the sender (`from`), the function initiates the transmission of the data packet to the next node (`_nextNode.send(packet)`). This step guarantees that the noted data is propagated to the subsequent node in the network, maintaining consistent backup copies across nodes. + +#### Importance in Data Continuity: +- **Continuous Recording:** The function ensures the continuous recording of essential data within the blockchain network. By noting and securely storing pertinent information, the function contributes to the comprehensive and uninterrupted documentation of blockchain transactions and activities. +- **Secure Storage:** Noted data is securely stored in designated nodes, protecting it from unauthorized access or tampering. The secure storage of noted information reinforces the network's reliability and trustworthiness. +- **Synchronized Backups:** By initiating the backup process for noted data, the function ensures that synchronized backup copies are consistently maintained across nodes. Synchronized backups enhance the network's resilience, enabling seamless data recovery in the event of node failures or unforeseen incidents. + +In summary, `noteBackupData(data, from, packet)` plays a vital role in preserving data continuity and ensuring the secure archiving of blockchain information. By facilitating continuous recording, secure storage, and synchronized backups, this function enhances the blockchain network's reliability, consistency, and resilience. Its contribution to maintaining a seamless flow of information reinforces the network's trustworthiness and robustness, fostering a dependable and resilient blockchain ecosystem. + + +### Ensuring Data Migration and Preservation: Storing Migrated Blockchain Data + +The JavaScript function `storeMigratedData(data)` serves a critical role in the blockchain network by managing the storage of migrated blockchain data. During the migration process, preserving the integrity and accessibility of migrated data is paramount. Let's explore the key functionalities and significance of this function in the context of data migration and preservation: + +#### Core Functionality: +- **Data Reception:** The function receives `data`, representing the migrated data that needs to be stored securely within the blockchain network. This data typically includes essential information related to blockchain transactions, ensuring that historical data is preserved during migration processes. +- **Closest Node Determination:** The function determines the closest node (`closestNode`) to the intended recipient of the migrated data (`data.receiverID`). This step is crucial for directing the migrated data to the most suitable storage location within the network. +- **Data Storage:** The function verifies whether the `closestNode` is among the nodes designated for serving (`_list.serving`). If the node is identified as a serving node, the migrated data is stored securely in the corresponding database using the `DB.storeData(closestNode, data, true)` operation. This operation ensures that the migrated data is securely archived and accessible for future reference, even in the context of data migration scenarios. +- **Data Propagation:** Upon successful storage of the migrated data, the function initiates the transmission of the data packet to the next node (`_nextNode.send(packet_.construct({ type_: TYPE_.STORE_BACKUP_DATA, data: data }))`). This step facilitates the propagation of migrated data to subsequent nodes in the network, ensuring consistent storage across multiple nodes. + +#### Importance in Data Migration and Preservation: +- **Data Integrity:** By securely storing migrated data within the designated nodes, the function ensures the integrity and accuracy of the data during migration processes. Preserving data integrity is vital for maintaining the reliability and trustworthiness of the blockchain network. +- **Preservation of Historical Data:** Migrated data often includes historical transaction records and essential blockchain information. Storing this historical data guarantees the preservation of critical information, allowing users and stakeholders to access historical records for auditing, analysis, or reference purposes. +- **Network Consistency:** The consistent storage and propagation of migrated data across nodes enhance network consistency. Consistent data storage practices ensure that all nodes within the network have access to the same set of historical data, reinforcing the uniformity of information across the blockchain ecosystem. + +In summary, `storeMigratedData(data)` plays a pivotal role in ensuring the seamless migration and preservation of blockchain data. By preserving data integrity, safeguarding historical records, and maintaining network consistency, this function contributes significantly to the reliability, trustworthiness, and continuity of the blockchain network. Its role in securely archiving migrated data underscores its importance in preserving the blockchain's integrity and ensuring the availability of accurate and comprehensive historical records. + +### Safeguarding Data Integrity: Deleting Migrated Blockchain Data + +The JavaScript function `deleteMigratedData(data, from, packet)` serves a crucial role in the blockchain network by managing the deletion of migrated blockchain data. During the blockchain's lifecycle, it is imperative to maintain data integrity and ensure that outdated or obsolete data is removed accurately. Let's explore the key functionalities and significance of this function in the context of data deletion and network consistency: + +#### Core Functionality: +- **Data Deletion Request:** The function receives `data`, representing the data to be deleted, including the `snID` (Supernode ID) and the unique `vectorClock` identifying the specific data entry to be removed from the blockchain. This data deletion request ensures that outdated or irrelevant information is eliminated from the blockchain's storage. +- **Closest Node Determination:** The function determines the closest node (`closestNode`) to the intended recipient of the deletion request (`data.receiverID`). Accurate identification of the closest node is crucial for directing the deletion request to the appropriate storage location within the network. +- **Data Deletion:** The function verifies whether the `snID` is among the nodes designated for stored data (`_list.stored`). If the specified node is identified as a stored data node and the `vectorClock` exists within the node's database, the function initiates the deletion of the specified data entry using the `DB.deleteData(data.snID, data.vectorClock)` operation. This deletion process ensures the secure removal of outdated data, enhancing the blockchain's overall integrity. +- **Data Propagation:** Upon successful deletion of the specified data entry, the function initiates the transmission of the data deletion packet to the next node (`_nextNode.send(packet)`) in the network. Propagating the deletion request ensures that the removal of obsolete data is consistent across multiple nodes, maintaining uniformity within the blockchain ecosystem. + +#### Importance in Data Integrity and Network Consistency: +- **Data Cleanliness:** By facilitating the accurate deletion of outdated data, the function ensures that the blockchain remains clean and free from obsolete information. Removing irrelevant data enhances the overall quality and relevancy of the blockchain's stored content. +- **Network Consistency:** The consistent deletion of obsolete data across nodes promotes network consistency. Uniform data removal practices prevent discrepancies in stored information, reinforcing the synchronicity and reliability of the entire blockchain network. +- **Space Optimization:** Deleting outdated data not only maintains data integrity but also optimizes storage space within the blockchain nodes. Efficient space management contributes to the network's scalability and resource utilization efficiency. + +In summary, `deleteMigratedData(data, from, packet)` plays a pivotal role in safeguarding data integrity and maintaining network consistency within the blockchain ecosystem. By ensuring the accurate removal of obsolete data and propagating deletion requests, this function contributes significantly to the blockchain's reliability, cleanliness, and efficient resource utilization. Its role in maintaining the blockchain's integrity underscores its importance in promoting a robust and dependable blockchain network. + + +### Seamless Data Forwarding: Ensuring Continuity in the Blockchain Network + +The JavaScript function `forwardToNextNode(mode, data)` serves as a pivotal component in the blockchain network's data management strategy. This function focuses on forwarding specific types of data, denoted by the `mode` parameter, to the next node in the blockchain network. By efficiently directing data to its intended destination, this function ensures the seamless flow of information and sustains the network's continuity. Let's delve into the essential features and significance of this function within the blockchain ecosystem: + +#### Core Functionality: +- **Data Forwarding Modes:** The function supports multiple data forwarding modes, including 'TAG,' 'NOTE,' 'EDIT,' and 'DATA.' Each mode corresponds to a specific type of data within the blockchain network. By categorizing data into distinct modes, the function can precisely identify the nature of the information being transmitted. +- **Data Packet Construction:** Based on the specified `mode`, the function constructs a corresponding data packet tailored to the intended data type. The `modeMap` object maps each mode to its respective packet type, facilitating accurate packet creation for data transmission. +- **Next Node Forwarding:** Upon determining the appropriate data forwarding mode and constructing the corresponding packet, the function verifies the existence of the next node (`_nextNode.id`). If the next node is active and available, the function dispatches the prepared data packet to the next node in the network. This action ensures that the data seamlessly transitions to the subsequent stage of the blockchain network, maintaining the flow of information. + +#### Importance in Blockchain Continuity: +- **Data Consistency:** By forwarding specific data types to the next node, the function promotes data consistency throughout the blockchain network. Consistent data flow ensures that information remains up-to-date and synchronized across nodes, preventing discrepancies or data lag within the network. +- **Process Optimization:** The function optimizes the data management process by automating the forwarding of specific data types. This automation minimizes manual intervention and streamlines the data transmission process, enhancing overall operational efficiency. +- **Blockchain Integrity:** Ensuring the uninterrupted flow of data preserves the integrity of the blockchain. Seamless data forwarding supports the reliable storage, retrieval, and processing of information, reinforcing the blockchain's reliability and trustworthiness. + +In summary, `forwardToNextNode(mode, data)` plays a pivotal role in preserving the continuity of the blockchain network. By accurately categorizing and forwarding specific data types, the function maintains data consistency, optimizes operational processes, and upholds the blockchain's integrity. Its contribution to the seamless flow of information underscores its significance in sustaining a robust and reliable blockchain ecosystem. + + +### Data Migration Processor: Ensuring Smooth Transition in Blockchain Network Topology + +The JavaScript function `dataMigration(node_change, flag)` stands as a critical component in managing changes to the blockchain network's topology. During network alterations, such as node additions or removals, this function orchestrates a seamless transition, ensuring data integrity and consistent network operations. Let's explore the function's core features and its pivotal role in maintaining network stability: + +#### Core Functionality: +- **Topology Change Detection:** The function takes as input `node_change`, a map detailing changes in the network's node structure. It identifies newly added nodes (`new_nodes`) and nodes to be deleted (`del_nodes`). Detecting these changes is vital for orchestrating appropriate actions based on the network's evolving topology. +- **Node Reconnection:** If the current next node (`_nextNode.id`) is deleted, the function initiates the process of reconnecting to the next available node, preserving the network's continuity. Similarly, if new nodes are added between the current node and the next node, the function triggers the reconnection process to accommodate the network modifications. +- **Node Server Initialization:** In scenarios where no other nodes are online (neither next nor previous), the function takes charge of initializing the server for newly added nodes (`new_nodes`). It ensures that these nodes are integrated seamlessly into the network, creating tables and initializing necessary configurations. +- **Data Migration:** The function coordinates the migration of data for new nodes (`new_nodes`) and handles the deletion of data for nodes being removed (`del_nodes`). This process ensures that data is appropriately transferred or removed, aligning with the network's updated topology. +- **Timed Execution:** Timed delays are introduced between various stages of the data migration process (`MIGRATE_WAIT_DELAY`). These delays enable controlled, sequential execution, preventing race conditions and ensuring a smooth transition. + +#### Importance in Network Stability: +- **Data Integrity:** By managing data migration, the function safeguards data integrity during topology changes. It ensures that data is appropriately migrated or deleted, preventing data loss or inconsistencies within the network. +- **Network Continuity:** Seamless node reconnections and server initializations maintain the network's continuity. Disruptions due to node additions or removals are mitigated, enabling uninterrupted network operations. +- **Resource Optimization:** The function optimizes resource utilization by coordinating data migration in a controlled manner. Timed delays and sequential execution prevent resource overload, ensuring efficient network management. + +In summary, `dataMigration(node_change, flag)` serves as a linchpin in the blockchain network's stability during topology changes. By orchestrating node reconnections, server initializations, and data migrations, the function preserves data integrity, sustains network continuity, and optimizes resource utilization. Its role in ensuring a smooth transition underscores its significance in maintaining a robust and reliable blockchain ecosystem. + + +### Data Migration Sub-Process: Handling Deletion of Nodes + +The JavaScript function `dataMigration.process_del(del_nodes, old_kb)` operates as a vital sub-process within the broader data migration framework. This sub-process is specifically designed to handle the deletion of nodes (`del_nodes`) in the blockchain network. Its primary purpose is to ensure a seamless transition when nodes are removed from the network. Let's delve into the core functionalities and significance of this sub-process: + +#### Core Functionalities: +- **Node Selection:** The function first filters out nodes that need to be processed (`process_nodes`) from the list of nodes to be deleted (`del_nodes`). It focuses on nodes that are currently being served, ensuring that data migration is performed only for relevant nodes. + +- **Data Migration (Deletion):** For each selected node (`n`), the function initiates the data migration process to handle the deletion scenario. It reads all data streams associated with the node and migrates them to the appropriate destination. If the closest active node is among the serving nodes, the data is directly stored there. Alternatively, if the closest active node is different, the data is sent to that node for storage (`TYPE_.STORE_MIGRATED_DATA`). This meticulous migration ensures that no data is lost during the deletion process. + +- **Clean-Up Operations:** After successful data migration, the function removes the node from the internal list (`_list.delete(n)`) and drops the corresponding table from the database (`DB.dropTable(n)`). These clean-up operations are crucial for maintaining a streamlined database structure post-deletion. + +- **Resource Management:** The function optimizes resource usage by closing WebSocket connections (`ws_connections[c].close()`) after completing the migration process. This ensures efficient resource utilization within the network. + +#### Importance in Data Integrity and Network Continuity: +- **Data Preservation:** By meticulously migrating data streams associated with deleted nodes, the function preserves data integrity, ensuring that valuable information is not lost during node removal. + +- **Network Streamlining:** The clean-up operations, including table deletion and internal list removal, streamline the network structure. This ensures that the network remains optimized and organized even after node deletions. + +- **Resource Efficiency:** The function's resource management strategies, such as closing WebSocket connections, contribute to efficient resource usage, enhancing overall network performance. + +In summary, `dataMigration.process_del(del_nodes, old_kb)` plays a pivotal role in handling the deletion of nodes within the blockchain network. By preserving data integrity, streamlining the network structure, and optimizing resource usage, this sub-process ensures that the network continues to operate seamlessly even in the face of node removals. Its careful data migration techniques and clean-up operations underscore its significance in maintaining a robust and reliable blockchain ecosystem. + + +### Data Migration Sub-Process: Handling Addition of Nodes + +The JavaScript function `dataMigration.process_new(new_nodes)` is a critical sub-process within the data migration framework. It specifically addresses the scenario where new nodes (`new_nodes`) are added to the blockchain network. This sub-process ensures a smooth transition by migrating data associated with existing serving nodes to the newly added nodes. Let's explore the core functionalities and importance of this sub-process: + +#### Core Functionalities: +- **Node Selection:** The function focuses on processing nodes that are currently being served (`process_nodes`). It iterates through these nodes, initiating data migration operations for each one. + +- **Data Migration (Addition):** For each serving node (`n`), the function reads all data streams associated with that node. It identifies the closest active node (`closest`) for each data stream. If the closest node is among the newly added nodes (`new_nodes`), the function migrates the data stream to that node. It ensures that data streams are seamlessly transferred to the newly added nodes. + +- **Data Deletion:** After successful migration, the function deletes the migrated data from the original serving node. This deletion operation is crucial for maintaining data consistency and avoiding duplicates in the network. + +- **Notification to Next Node:** The function notifies the next node about the deleted migrated data. It sends a packet indicating the deletion (`TYPE_.DELETE_MIGRATED_DATA`) to ensure synchronization and coherence in the network. + +- **Resource Management:** The function manages resources effectively by closing WebSocket connections (`ws_connections[c].close()`) after completing the migration process. This resource optimization enhances overall network efficiency. + +#### Importance in Network Expansion and Data Synchronization: +- **Data Continuity:** By migrating existing data streams to newly added nodes, the function ensures the continuity of valuable information within the network. This seamless data transition is vital for maintaining a consistent blockchain history. + +- **Network Expansion:** The function facilitates network expansion by enabling the integration of new nodes. As the network grows, this sub-process plays a pivotal role in integrating these nodes without disrupting existing data flow. + +- **Data Synchronization:** The synchronization between serving nodes and newly added nodes is vital for network coherence. By deleting migrated data from the serving nodes and notifying the next node, the function promotes synchronized data handling across the network. + +In summary, `dataMigration.process_new(new_nodes)` is instrumental in handling the addition of nodes within the blockchain network. Its ability to ensure data continuity, facilitate network expansion, and maintain data synchronization underscores its significance in building a robust and scalable blockchain ecosystem. The meticulous data migration techniques and resource management strategies employed by this sub-process contribute to the seamless integration of new nodes, promoting the overall resilience and efficiency of the blockchain network. + + +### Data Migration Utility: Initiating Network-wide Refresh + +The JavaScript function `dataMigration.intimateAllNodes()` serves as a crucial utility within the data migration framework. This function initiates a network-wide refresh, ensuring that all nodes within the blockchain network synchronize and update their data. Let's delve into the key aspects and significance of this utility function: + +#### Core Functionality: +- **Network Connection:** The function establishes connections to all active nodes within the network using the `connectToAliveNodes()` function. This ensures that it communicates with all live nodes, fostering network-wide synchronization. + +- **Packet Construction:** The function constructs a special packet (`packet`) with a designated type (`TYPE_.INITIATE_REFRESH`). This packet serves as a signal to all nodes, indicating the need for a comprehensive data refresh and synchronization. + +- **Packet Transmission:** For each active node (`n`), the function sends the constructed packet. This transmission triggers the refresh process on the receiving nodes, prompting them to update their data and align with the latest blockchain state. + +- **Connection Closure:** After sending the refresh packet, the function closes the WebSocket connections to the nodes (`ws_connections[n].close()`). This strategic closure optimizes network resources, ensuring efficient usage of WebSocket connections. + +#### Importance in Network Maintenance and Consistency: +- **Global Data Synchronization:** By initiating a network-wide refresh, the function plays a pivotal role in ensuring global data synchronization. All nodes receive the synchronization signal simultaneously, leading to a coordinated effort to update their respective datasets. + +- **Data Consistency:** The utility function contributes to maintaining data consistency across the blockchain network. When all nodes refresh their data concurrently, it minimizes discrepancies, aligns transaction histories, and upholds the integrity of the blockchain ledger. + +- **Network Health:** Periodic network-wide refreshes are essential for the overall health and stability of the blockchain network. They prevent data fragmentation, resolve inconsistencies, and promote a harmonized blockchain state, enhancing the network's resilience. + +In summary, `dataMigration.intimateAllNodes()` serves as a linchpin in network maintenance and data consistency efforts. Its ability to orchestrate a synchronized refresh across all active nodes fosters a unified blockchain state. By promoting global data synchronization and ensuring data consistency, this utility function contributes significantly to the long-term stability and reliability of the blockchain network. + + +### Logging Network State: Real-time Monitoring and Analysis + +The JavaScript code snippet provided initiates a logging mechanism that offers real-time insight into the network's state. Through regular intervals, the code captures and displays essential network information, providing visibility into key components. Let's explore the significance and implications of this logging functionality: + +#### Core Functionality: +- **Interval Setup:** The code establishes a periodic logging interval using `setInterval()`. At specific intervals (defined by `RETRY_TIMEOUT`), the designated function executes, capturing the network state for analysis. + +- **Network Components:** Within the logging function, the code retrieves and logs three critical pieces of information: + 1. `_prevNode.id`: ID of the previous node in the network. + 2. `_nextNode.id`: ID of the next node in the network. + 3. `_list.get()`: Retrieves the current state of the network components, likely providing a structured representation of node statuses, connections, or other pertinent details. + +- **Logging Method:** The function utilizes `console.debug()` to output the captured network information. This logging method ensures that the information is displayed for developers and network administrators to monitor. + +#### Significance in Network Management: +- **Real-time Monitoring:** The logging mechanism facilitates real-time monitoring of the network's vital components. Network administrators can observe changes in the previous and next node assignments, allowing them to identify patterns or issues promptly. + +- **Debugging and Troubleshooting:** In case of unexpected network behavior or issues, the logged information provides valuable context for debugging and troubleshooting. Developers can analyze the logged data to pinpoint potential areas of concern and implement targeted solutions. + +- **Resource Optimization:** By monitoring the network state, administrators can optimize resource allocation and node assignments. This proactive approach enables efficient utilization of resources, ensuring that each node functions optimally within the network ecosystem. + +- **Data-Driven Decisions:** Access to detailed network metrics empowers decision-making processes. Administrators can make informed decisions based on the logged data, allowing them to implement strategic changes or enhancements to improve the network's overall performance and reliability. + +In summary, the logging mechanism offers a window into the network's inner workings, enabling real-time analysis and informed decision-making. By capturing essential network components at regular intervals, this functionality contributes to efficient network management, proactive issue resolution, and the continuous enhancement of the blockchain ecosystem. + + +### Network Refresh Initiation: Understanding `initiateRefresh()` Function + +The provided JavaScript function, `initiateRefresh()`, serves a pivotal role in network management, particularly in the context of blockchain systems. Let's explore the purpose and implications of this function: + +#### Core Functionality: +- **Network Refresh Trigger:** The `initiateRefresh()` function acts as a trigger for initiating a network refresh process. Upon invocation, it commences the refresh operation, which likely involves synchronization, data validation, or other network-wide processes. + +- **`refresher.invoke(false)`:** Within the function, the code invokes a method or function named `invoke()` on an object or module named `refresher`. The method is invoked with a `false` parameter, indicating a specific mode or configuration for the refresh operation. The exact behavior and functionality of this `invoke()` method depend on the implementation details of the `refresher` object or module. + +#### Significance and Use Cases: +- **Data Consistency:** Network refreshes are crucial for maintaining data consistency across nodes in a decentralized blockchain network. By triggering a refresh, the system can synchronize data, ensuring that all nodes have access to the latest and most accurate information. + +- **Conflict Resolution:** In decentralized systems, conflicts or inconsistencies might arise due to concurrent transactions or network disruptions. Initiating a refresh can enable conflict resolution mechanisms, resolving discrepancies and ensuring the integrity of the blockchain data. + +- **Node Health:** Network refreshes can also be used as a health-check mechanism for individual nodes. By participating in the refresh process, nodes can confirm their operational status and validate their data against the network consensus, ensuring they are up-to-date and functioning correctly. + +- **Chain Integrity:** Blockchain networks rely on the integrity of the entire chain. Initiating a refresh allows nodes to validate the integrity of the blockchain, ensuring that every block, transaction, and data element adheres to the network's predefined rules and consensus protocols. + +- **Network Upgrades:** During network upgrades or protocol changes, initiating a refresh can facilitate the smooth transition of nodes to the updated version. It allows nodes to adapt to the new protocol, ensuring compatibility and continuity in the blockchain's operation. + +#### Implementation Considerations: +- **Error Handling:** The function might include error handling mechanisms, ensuring that any errors or exceptions occurring during the refresh process are captured and appropriately managed. Error handling is critical for maintaining network stability and reliability. + +- **Asynchronous Nature:** Depending on the complexity of the refresh operation, the function might execute asynchronously. Asynchronous execution ensures that the network refresh does not block the main thread, allowing the system to remain responsive and continue processing other tasks concurrently. + +In summary, `initiateRefresh()` serves as a pivotal control point for network-wide synchronization and data validation in blockchain systems. By invoking this function, network administrators can ensure data consistency, resolve conflicts, maintain node health, preserve chain integrity, and facilitate seamless network upgrades, contributing to the robustness and reliability of the decentralized blockchain ecosystem. diff --git a/docs/main.md b/docs/main.md new file mode 100644 index 0000000..c5f1344 --- /dev/null +++ b/docs/main.md @@ -0,0 +1,322 @@ +## `startNode()` + +This function initializes the Node application, performing necessary setup procedures and connecting to the database. + +### Parameters + +None + +### Usage + +```javascript +startNode(); +``` + +### Description + +The `startNode()` function performs a series of crucial operations to initialize the Node application: + +1. **Read Configuration:** + - Reads configuration settings from the `../args/config.json` file, providing essential parameters for the application's behavior. + +2. **Retrieve Password:** + - Parses command line arguments to extract the password provided via the `-password=` flag. This password is used for decrypting sensitive information. + +3. **Load Private Key:** + - Loads private keys from the `../args/keys.json` file. These keys are then decrypted using the password obtained from the command line arguments. The decrypted keys are essential for secure communication and data integrity. + +4. **Database Connection:** + - Initializes a connection to the database using the credentials provided in the configuration file. This step is vital for storing and retrieving data during the application's runtime. + +5. **Load Base Data:** + - Retrieves essential base data from the database. This data includes critical information necessary for the application's core functionality. The retrieved data is then set in `floGlobals` variables, making it accessible throughout the application. + +6. **Refresh Data:** + - Initiates a data refresh process, ensuring that the application's data remains up-to-date and synchronized with the database. This step is essential for maintaining the integrity of the information used by the application. + +7. **Start Server:** + - Instantiates a server using the port specified in the configuration file. The server acts as a communication interface, allowing clients to interact with the application. Proper configuration of the server is fundamental for handling incoming requests and responses effectively. + +These operations collectively prepare the Node application for execution, ensuring that it is properly configured, securely authenticated, and connected to the necessary data sources. Each step is essential for the application to function smoothly and provide the intended services. + +### Important Notes + +- **Ensure Configuration Files:** Make sure that the necessary configuration files (`config.json` and `keys.json`) are present in the specified paths. These files contain crucial settings and cryptographic keys required for the proper functioning of the application. + +- **Implement Proper Error Handling:** Proper error handling mechanisms should be implemented for real-world applications. This ensures graceful handling of errors and prevents unexpected failures, providing a better user experience and easier troubleshooting. + +- **Logging:** Implement a robust logging system to track the application's behavior, errors, and other relevant events. Logging is invaluable for debugging and monitoring the application in production environments. + +### Dependencies + +The `startNode()` function relies on the following dependencies: + +- **floCrypto:** This dependency is used for retrieving and decrypting Shamir secrets. It plays a vital role in securely handling sensitive information within the application. + +- **Crypto:** This is presumed to be either a custom or an external library for cryptographic operations. Cryptographic operations are essential for ensuring data security, integrity, and authentication. + +- **DB:** This is presumed to be a custom module responsible for handling database operations. It likely includes functionalities for creating, retrieving, updating, and deleting data in the connected database. + +- **Server:** This is presumed to be a custom module used for setting up a server. The server module facilitates communication between clients and the application, handling incoming requests and providing appropriate responses. + +- **intra:** This is presumed to be a custom module designed for handling internal communication within the application. Internal communication modules are essential for components within the application to exchange data and coordinate activities. + +These dependencies are crucial components of the application architecture, each serving a specific purpose in ensuring the application's functionality, security, and efficiency. + + +## `DB.createBase()` + +This function initializes the creation of base tables in the database. + +### Description + +The `DB.createBase` function performs the following operations: + +- **Table Creation:** + - Iterates through the `Base_Tables` object, which presumably contains table names as keys and corresponding column definitions as values. + - Constructs SQL `CREATE TABLE` statements based on the `Base_Tables` object. + - Executes SQL statements to create tables in the database if they do not already exist. + +### Parameters + +None + +### Returns + +A Promise that resolves when all the table creation statements are successfully executed. The promise resolves with an array of results for each executed SQL statement. + +### Important Notes + +- Ensure that the `Base_Tables` object is properly defined with table names as keys and corresponding column definitions as values. +- Proper error handling and logging should be implemented for real-world applications to handle any database-related issues. +- Database connection and query execution methods (`queryResolve` in this case) should be appropriately implemented for this function to work as intended. + +### `selfDiskMigration(node_change)` + +Migrates data from nodes that have undergone changes as per the provided `node_change` object. + +**Parameters:** +- `node_change` (object): An object indicating changes in nodes. + +**Explanation:** +- The `selfDiskMigration` function migrates data from nodes that have undergone changes as specified in the `node_change` object. It performs the following operations for each node in the provided list of tables: + 1. If the node is marked as `false` in the `node_change` object, it drops the corresponding table from the database. + 2. It reads all data from the node's table and identifies the closest cloud node using the `cloud.closestNode()` function. + 3. If the closest cloud node is different from the current node, it deletes the data entry from the current node's table. + +**Usage:** +```javascript +const DB = require('your-database-module'); +const cloud = require('your-cloud-module'); + +function selfDiskMigration(node_change) { + DB.listTable("SHOW TABLES") + .then(disks => { + disks.forEach(n => { + if (node_change[n] === false) + DB.dropTable(n) + .then(_ => null) + .catch(e => console.error(e)); + + DB.readAllDataStream(n, 0, d => { + let closest = cloud.closestNode(d.receiverID); + if (closest !== n) + DB.deleteData(n, d.vectorClock) + .then(_ => null) + .catch(e => console.error(e)); + }) + .then(result => console.debug(`Completed self-disk migration for ${n}`)) + .catch(error => console.error(error)); + }); + }) + .catch(error => console.error(error)); +}; +``` + +## `diskCleanUp(base)` + +Cleans up data based on the provided base configuration. + +**Parameters:** +- `base` (object): The base configuration object containing necessary data for cleanup. + +**Explanation:** +- The `diskCleanUp` function cleans up data based on the provided base configuration. It performs the following operations for each serving supernode: + 1. Deletes all unauthorized app data for the given supernode and authorized applications. + 2. For each authorized application: + - Deletes unofficial data entries (untagged, unknown sender/receiver) for the specified supernode. + 3. Resolves the promise when the cleanup process is finished. + +**Note:** +- Ensure that the necessary database and intra-modules are properly imported and initialized in your application. +- Customize the logic inside the function based on your specific use case and database configuration. +- Proper error handling is crucial for robust cleanup functionality. Make sure to handle errors and exceptions as per your application's requirements. + +## `base` Object Properties + +The `base` object returned after loading data from the database contains the following properties: + +#### `base.supernodes` + +- **Type**: `object` +- **Description**: Information about supernodes in the system. + +#### `base.sn_config` + +- **Type**: `object` +- **Description**: Configuration settings for supernodes. + +#### `base.appList` + +- **Type**: `object` +- **Description**: List of applications in the system. + +#### `base.appSubAdmins` + +- **Type**: `object` +- **Description**: Sub-admins for applications. + +#### `base.appTrustedIDs` + +- **Type**: `object` +- **Description**: Trusted IDs for applications. + +**Note:** +- The properties of the `base` object contain essential data loaded from the database and are used throughout the application for various functionalities. +- Make sure to handle these properties appropriately in your application logic and error scenarios. +- Customize the usage of these properties based on your specific application requirements. + +## `refreshData` Object + +The `refreshData` object is responsible for managing the refreshing process in the application. It contains the following properties and methods: + +#### `refreshData.count` + +- **Type**: `number` +- **Description**: Represents the countdown value for refreshing data. It decrements with each iteration of the refresh process. + +#### `refreshData.base` + +- **Type**: `object` +- **Description**: Contains the base data for the refresh process, including supernodes, configurations, applications, sub-admins, and trusted IDs. + +#### `refreshData.refresh_instance` + +- **Type**: `object` +- **Description**: Represents the interval instance for the refresh process. It is used to manage the interval at which data is refreshed. + +#### `refreshData.invoke(flag = true)` + +- **Parameters**: + - `flag` (boolean, optional): A flag indicating whether to force the refresh (default is `true`). + +- **Returns**: `Promise` +- **Description**: Initiates the refresh process. It refreshes blockchain data, performs disk clean-up, and manages the refreshing interval. + +#### `refreshData.countdown` + +- **Description**: Decrements the countdown value. When the countdown reaches zero or below, it triggers the `invoke()` method to refresh the data. + +**Note:** +- The `refreshData` object is essential for maintaining the consistency of data in the application. +- Ensure that the countdown value and refresh intervals are configured appropriately based on your application requirements. +- Handle errors and warnings from the refresh process to maintain the application's stability and reliability. + +### `refreshBlockchainData(base, flag)` + +This function is responsible for refreshing blockchain data for the application. It communicates with external APIs, updates supernode configurations, and retrieves application sub-admin lists. The function operates asynchronously using promises and provides detailed logs for debugging purposes. + +#### Parameters + +- `base` (object): The base data for the refresh process, including supernodes, configurations, applications, sub-admins, and trusted IDs. +- `flag` (boolean): A flag indicating whether to force the refresh. + +#### Returns + +- **Type**: `Promise` +- **Description**: A promise that resolves with a string indicating the status of the data refresh process. + +#### Explanation + +1. The function initiates the data refresh process by calling external APIs and updating the supernode configurations based on the provided `base` data. + +2. It logs the result of the supernode configuration update, including any errors or warnings encountered during the process. + +3. The function then communicates with the cloud service using the provided supernode storage ID and a list of supernodes obtained from the `floGlobals` object. + +4. It logs the ordered list of nodes obtained from the cloud service, providing insights into the current node configuration. + +5. The function retrieves the application sub-admin lists from the blockchain using the `base` data, ensuring the application has the latest sub-admin information. + +6. It logs the result of the application sub-admin list update, including any warnings or errors. If there are errors, they are captured as warnings to avoid disrupting the refresh process. + +7. Finally, the function resolves the promise with a message indicating that the data has been successfully refreshed from the blockchain. If there are errors during the process, they are captured and passed to the rejection handler of the promise. + +#### Note + +- Handle any errors or warnings returned during the blockchain data refresh process to maintain the stability and reliability of the application. +- Ensure that the provided `base` data is accurate and up-to-date to obtain the latest information from the blockchain. + +## `readSupernodeConfigFromAPI(base, flag)` + +This function reads supernode configurations from an external API and updates the local database and application state accordingly. It processes data related to new nodes, updated nodes, removed nodes, configuration settings, and application entries. The function operates asynchronously using promises and provides detailed logs for debugging purposes. + +#### Parameters + +- `base` (object): The base data for the application, including supernodes, configurations, applications, sub-admins, and trusted IDs. +- `flag` (boolean): A flag indicating whether the data read operation is forced or not. + +#### Returns + +- **Type**: `Promise` +- **Description**: A promise that resolves with a string indicating the status of the supernode configuration update process. + +#### Explanation + +1. The function constructs query options for reading data from the blockchain API. It includes parameters such as `sentOnly` to retrieve sent data only, `pattern` to specify the data pattern (in this case, "SuperNodeStorage"), and `after` to fetch data after a specific transaction ID. + +2. It calls the external blockchain API to read data related to supernode configurations. The received data is processed to identify new nodes, updated nodes, removed nodes, configuration changes, and application entry modifications. + +3. For each type of data change, the function updates the local database using appropriate database operations (e.g., `DB.rmSuperNode` to remove nodes, `DB.addSuperNode` to add new nodes, etc.). It also updates the corresponding entries in the `base` object to reflect the changes in the application state. + +4. The function ensures that all database operations are executed successfully. If any operation fails, it captures the errors as warnings, indicating that some data might not have been saved correctly. + +5. If there are changes in supernodes (new nodes, updated nodes, or removed nodes), the function triggers data migration processes. The specific data migration method (`selfDiskMigration` or `intra.dataMigration`) is chosen based on the presence of the `flag` parameter. If `flag` is `null`, it implies that the migration process has already taken place, so only node changes are processed using `selfDiskMigration`. If `flag` is provided, indicating a forced update, it triggers `intra.dataMigration` to handle the migration process. + +6. Finally, the function resolves the promise with a message indicating that the supernode configuration has been successfully updated. If there are errors during the process, they are captured and passed to the rejection handler of the promise. + +#### Note + +- Handle any errors or warnings returned during the supernode configuration update process to maintain the stability and reliability of the application. +- Ensure that the provided `base` data is accurate and up-to-date to obtain the latest information from the blockchain. + +## `readAppSubAdminListFromAPI(base)` + +This function reads sub-administrator lists and trusted IDs for all registered applications from an external API. It processes data related to adding and removing sub-administrators and trusted IDs for each application. The function operates asynchronously using promises and provides detailed logs for debugging purposes. + +#### Parameters + +- `base` (object): The base data for the application, including supernodes, configurations, applications, sub-admins, and trusted IDs. + +#### Returns + +- **Type**: `Promise` +- **Description**: A promise that resolves with a string indicating the status of the sub-administrator and trusted ID list loading process. + +#### Explanation + +1. The function iterates through each registered application in the `base.appList` object. For each application, it constructs query options for reading data from the blockchain API. The options include parameters such as `sentOnly` to retrieve sent data only, `pattern` to specify the application name, and `after` to fetch data after a specific transaction ID. + +2. It calls the external blockchain API to read data related to sub-administrator lists and trusted IDs for the current application. The received data is processed to identify added and removed sub-administrators and trusted IDs. + +3. For each application, the function updates the local database using appropriate database operations (e.g., `DB.setSubAdmin` and `DB.setTrustedIDs`) to reflect the changes in sub-administrator lists and trusted IDs. It also updates the corresponding entries in the `base` object to maintain the application state. + +4. The function ensures that all database operations are executed successfully. If any operation fails, it captures the errors as warnings, indicating that the sub-administrator or trusted ID list might not have been saved correctly. + +5. After processing data for all applications, the function resolves the outer promise with a message indicating that the sub-administrator and trusted ID lists have been successfully loaded for all applications. If there are errors during the process, they are captured and passed to the rejection handler of the outer promise. + +#### Note + +- Handle any errors or warnings returned during the sub-administrator and trusted ID list loading process to maintain the accuracy of application permissions and security. +- Ensure that the provided `base` data is accurate and up-to-date to obtain the latest information from the blockchain. + diff --git a/docs/server.md b/docs/server.md new file mode 100644 index 0000000..3ed5e05 --- /dev/null +++ b/docs/server.md @@ -0,0 +1,97 @@ +### HTTP Server Request Handling + +The provided code snippet demonstrates the request handling logic of an HTTP server. Below is an explanation of the code's functionality: + +#### Functionality: + +- The code creates an HTTP server using `http.createServer((req, res) => {...})`, defining a callback function to handle incoming requests. +- The server sets the "Access-Control-Allow-Origin" header to allow requests from any origin (`*`). +- The server distinguishes between HTTP GET requests and other request methods. + - For GET requests, the server parses the query parameters from the request URL using the `url.parse(req.url, true)` method. + - If the URL does not contain search parameters, the server responds with an empty body. + - If search parameters are present, the server processes the request using `client.processRequestFromUser(u.query)`. + - If processing is successful, the server sends the response as a JSON object using `res.end(JSON.stringify(result[0]))`. + - If an error occurs during processing: + - If the error is an instance of `INVALID`, the server responds with the error message and the corresponding HTTP status code. + - For other errors, the server logs the error, responds with an internal error message, and sets the appropriate HTTP status code. + +#### Request Handling Logic: + +- The server's primary function is to handle GET requests containing query parameters. +- It processes the query parameters and communicates with the `client` module to generate a response. +- Successful responses are sent back to the client in JSON format, providing the requested data. +- Error handling ensures that appropriate error messages and status codes are returned to the client, enhancing the server's reliability and user experience. + +This HTTP server logic allows clients to request specific data via GET requests and receive tailored responses, enabling seamless interaction between clients and the server. + +### HTTP Server POST Request Handling + +POST Request handles incoming HTTP POST requests. H + +#### Functionality: + +- The code checks if the incoming request method is "POST". +- For POST requests, the server processes the data sent in the request body. + - The server listens for data chunks and assembles them into a complete data string using the `req.on('data', chunk => data += chunk)` event. + - Once all data is received (`req.on('end', ...) event`), the server processes the data using `client.processIncomingData(data)`. + - If processing is successful, the server sends the response as a JSON object using `res.end(JSON.stringify(result[0]))`. + - The response data includes the processed information. + - If a processing mode (`result[1]`) is provided, specific actions are taken based on the mode: + - If the mode is 'DATA', 'EDIT', 'TAG', or 'NOTE', the processed data is sent to live requests using `sendToLiveRequests(result[0])`. + - Additionally, the processed data is forwarded to the next node in the network using `intra.forwardToNextNode(result[1], result[0])`. + - The server also decrements the countdown timer using `refresher.countdown`. + - If an error occurs during processing: + - If the error is an instance of `INVALID`, the server responds with the error message and the corresponding HTTP status code. + - For other errors, the server logs the error, responds with an internal error message, and sets the appropriate HTTP status code. + +#### Request Handling Logic: + +- The server's POST request handling logic focuses on processing incoming data. +- Data sent via POST requests is processed, allowing various modes of operation ('DATA', 'EDIT', 'TAG', 'NOTE') to be executed based on the content of the request. +- Processed data is sent to live requests and forwarded to the next node, facilitating real-time data synchronization and network communication. +- Error handling ensures that appropriate error messages and status codes are returned to the client, enhancing the server's reliability and user experience. + +This POST request handling logic enables clients to send data to the server, trigger specific actions, and receive real-time updates, enhancing the server's interactive capabilities and data synchronization functionalities. + + + +### WebSocket Server Functionality + +The provided code snippet demonstrates the functionality of a WebSocket server that handles incoming messages from clients. Here's an overview of how the server processes messages without including initialization details: + +#### Connection Handling and Message Processing: + +- When a client establishes a connection, the server listens for incoming messages on that connection. +- Upon receiving a message, the server checks if it starts with `intra.SUPERNODE_INDICATOR`. + - If it does, the server processes the message as a task from a supernode using `intra.processTaskFromSupernode(message, ws)`. + - If not, the server treats the message as a JSON object sent by a user. +- The server attempts to parse the incoming JSON request. + - If the request contains a `status` field, indicating a status update from the user, the server processes it using `client.processStatusFromUser(request, ws)`. + - If the request doesn't contain a `status` field, it is treated as a user request. The server processes the request using `client.processRequestFromUser(request)`. +- If processing is successful, the server sends the response back to the user via the WebSocket connection (`ws.send(JSON.stringify(result[0]))`). +- Errors encountered during processing are handled. If configured (`floGlobals.sn_config.errorFeedback`), appropriate error messages are sent back to the user. + +#### Error Handling: +- If the incoming message is not in valid JSON format, the server sends an error message indicating that the request is not in JSON format. + +This server setup allows bidirectional communication between clients and the server, enabling the processing of tasks and user requests in a real-time manner. + +### Broadcasting Data to Live Requests + +The provided function `sendToLiveRequests(data)` broadcasts data to all live WebSocket requests based on certain conditions. Here's an explanation of how this function works: + +#### Functionality: + +- The function takes a `data` parameter, representing the data to be sent to live WebSocket requests. +- It iterates over all connected WebSocket clients stored in the `wsServer.clients` set. +- For each client, it checks if the client's active request (stored in `ws._liveReq`) satisfies specific conditions using `client.checkIfRequestSatisfy(ws._liveReq, data)`. + - If the client's request matches the conditions, the function sends the `data` to that client in JSON format using `ws.send(JSON.stringify(data))`. + +#### Broadcasting Logic: + +- The function acts as a broadcast mechanism, allowing targeted messages to be sent to specific clients based on their active requests. +- The conditions specified in `client.checkIfRequestSatisfy(ws._liveReq, data)` determine which clients receive the broadcasted data. +- Clients with active requests that meet the specified conditions will receive the `data` object. + +This functionality enables real-time communication with clients by delivering tailored data updates to specific active requests, enhancing the efficiency and responsiveness of the WebSocket server. + diff --git a/docs/sync.md b/docs/sync.md new file mode 100644 index 0000000..1b6fd10 --- /dev/null +++ b/docs/sync.md @@ -0,0 +1,270 @@ + + +### Queue-Based Data Synchronization: Understanding `queueSync` Object + +The provided JavaScript object, `queueSync`, encapsulates a queue-based data synchronization mechanism used in a blockchain or distributed system. This synchronization method ensures orderly and efficient synchronization of blocks between nodes. Let's delve into the key components and functionalities of the `queueSync` object: + +#### Object Structure: +- **Properties:** + - **`list`:** A dictionary that maintains synchronization states for different nodes. Each node's synchronization state includes information about the WebSocket connection (`ws`), timestamps, a queue of blocks to sync (`q`), currently syncing blocks (`cur`), verified blocks (`ver`), and block hashes (`hashes`). + +#### Core Functionalities: +- **Initialization (`init` Method):** + - The `init` method initializes the synchronization process for a specific node (`node_i`). It creates a synchronization state entry in the `list` dictionary and triggers the synchronization by requesting block hashes from the node. + +- **Adding Blocks to Sync (`add_block` Method):** + - The `add_block` method adds a block (`block_n`) to the synchronization queue for a specific node (`node_i`). If the node is already syncing blocks, the new block is queued; otherwise, it initiates the synchronization of the block. + +- **Ending Block Sync (`end_block` Method):** + - The `end_block` method marks the completion of syncing a specific block (`block_n`) for a node (`node_i`). It updates the synchronization state, verifying the block's hash after a timeout. If the hash verification fails, the block is resynced. + +- **Handling Last Block (`last_block` Method):** + - The `last_block` method indicates the last block (`block_n`) for a node (`node_i`). It sets up an interval to continuously check if all blocks have been synced and verified. Once synchronization is complete, it removes the synchronization state entry and triggers the ordering of the next backup node. + +#### Synchronization Workflow: +1. **Initialization:** The synchronization process begins with the `init` method, initiating the synchronization state for a specific node. +2. **Adding Blocks:** Blocks are added to the synchronization queue using the `add_block` method, ensuring orderly processing. +3. **Syncing Blocks:** Blocks in the queue are processed and synchronized using the `cur` set, ensuring one block is synced at a time. +4. **Verification:** After syncing, blocks are verified using their hashes, ensuring data integrity. +5. **Completion:** When all blocks are synced, verified, and the queue is empty, the synchronization process is marked as complete. +6. **Ordering:** After synchronization, the object signals the next backup node to order blocks. + +#### Usage Considerations: +- **Efficiency:** The queue-based approach ensures efficient synchronization, allowing nodes to process blocks sequentially without overwhelming network resources. +- **Error Handling:** The mechanism includes error handling, such as hash verification, ensuring data integrity during the synchronization process. +- **Orderly Processing:** Blocks are synchronized and verified in an orderly manner, preventing race conditions and data inconsistencies. + +In summary, the `queueSync` object provides a structured and systematic approach to data synchronization between nodes in a distributed system. By ensuring order, efficiency, and integrity, this mechanism contributes to the reliability and consistency of the blockchain network. + + +### Requesting Data Synchronization: Understanding `requestDataSync` Function + +The `requestDataSync` function plays a pivotal role in initiating the data synchronization process for a specific node (`node_i`). By invoking the `init` method of the `queueSync` object, this function triggers the synchronization workflow, ensuring the orderly and efficient synchronization of blocks between nodes. + +#### Function Overview: +- **Function Name:** `requestDataSync(node_i, ws)` +- **Parameters:** + - **`node_i` (String):** Identifier of the node for which data synchronization is requested. + - **`ws` (WebSocket):** WebSocket connection object representing the communication channel with the specified node. +- **Functionality:** + - The `requestDataSync` function is responsible for initiating the data synchronization process for a targeted node in a distributed system. + - It utilizes the `init` method of the `queueSync` object, which sets up the synchronization state, initiates the synchronization process, and handles the sequential syncing of blocks. + +#### Key Considerations: +- **Targeted Synchronization:** The function enables selective synchronization by specifying the target node (`node_i`), allowing precise control over which node's data is synchronized. +- **WebSocket Connection:** The function relies on a WebSocket connection (`ws`) to establish communication with the specified node, facilitating the exchange of synchronization-related messages. + +#### Workflow Summary: +1. **Initialization:** The function triggers the `init` method of the `queueSync` object, initializing the synchronization process for the specified node (`node_i`). +2. **Synchronization Setup:** The `init` method sets up the synchronization state, including the WebSocket connection and synchronization-related data structures. +3. **Block Synchronization:** Blocks are sequentially added to the synchronization queue and processed, ensuring a methodical synchronization process. +4. **Data Integrity:** During synchronization, block hashes are verified to maintain data integrity and consistency. +5. **Completion:** Once all blocks are successfully synchronized and verified, the synchronization process is marked as complete. + +In essence, the `requestDataSync` function serves as a catalyst for data synchronization, facilitating the seamless exchange of blockchain blocks between nodes. Its targeted and systematic approach ensures the accuracy and reliability of synchronized data, contributing to the overall robustness of the distributed system. + + +### Sending Block Hashes: Understanding `sendBlockHashes` Function + +The `sendBlockHashes` function serves as a critical component in the process of sharing block hashes with a designated node (`node_i`). By extracting block hashes from the local database and sending them via a WebSocket connection (`ws`), this function ensures the accurate transmission of blockchain data between nodes. + +#### Function Overview: +- **Function Name:** `sendBlockHashes(node_i, ws)` +- **Parameters:** + - **`node_i` (String):** Identifier of the node for which block hashes are being sent. + - **`ws` (WebSocket):** WebSocket connection object representing the communication channel with the specified node. +- **Functionality:** + - The `sendBlockHashes` function retrieves block hashes from the local database corresponding to the specified node (`node_i`). + - Block hashes are transmitted in a sequential manner to the target node via the provided WebSocket connection (`ws`). + - The function includes error handling mechanisms to address potential database querying issues and ensure reliable transmission. + +#### Key Considerations: +- **Database Querying:** The function performs a database query to extract block hashes, utilizing the appropriate SQL statements and database table structures. +- **Sequential Transmission:** Block hashes are sent one at a time in a sequential manner, ensuring systematic and organized transmission. +- **Validation:** The transmitted block hashes are validated by the receiving node to maintain data integrity and consistency across the distributed system. +- **Acknowledgment:** The receiving node is expected to acknowledge the receipt of block hashes, confirming successful data transmission. + +#### Workflow Summary: +1. **Database Query:** The function executes a database query to fetch block hashes corresponding to the specified node (`node_i`). +2. **Transmission:** Block hashes are sent sequentially to the target node (`node_i`) through the WebSocket connection (`ws`). +3. **Acknowledgment:** The receiving node acknowledges the receipt of block hashes, confirming the successful transmission and enabling further synchronization processes. + +The `sendBlockHashes` function plays a crucial role in the blockchain synchronization process, ensuring the accurate exchange of block data between nodes. Its organized and methodical approach supports the reliability and consistency of blockchain data, contributing to the overall stability of the distributed network. + + +### Verifying Block Hashes and Handling Hash Mismatches: Understanding `checkBlockHash` Function + +The `checkBlockHash` function is a vital component of the blockchain synchronization process, ensuring data integrity by verifying the received block hash (`hash`). When a hash mismatch occurs, indicating a potential inconsistency in the data, the function takes proactive measures to request the corresponding block data for re-synchronization. This function is crucial for maintaining the accuracy and reliability of blockchain data across distributed nodes. + +#### Function Overview: +- **Function Name:** `checkBlockHash(node_i, block_n, hash)` +- **Parameters:** + - **`node_i` (String):** Identifier of the node for which the block hash is being checked. + - **`block_n` (Integer):** Block number corresponding to the hash being verified. + - **`hash` (String):** Hash value of the block data received from the specified node (`node_i`). +- **Functionality:** + - The `checkBlockHash` function verifies the received block hash (`hash`) for a specific block number (`block_n`) of the specified node (`node_i`). + - If the hash verification indicates a mismatch, implying a potential data inconsistency, the function triggers a request to the source node (`node_i`) for re-synchronization of the corresponding block data. + - The function utilizes the `verifyBlockHash` function to perform hash verification, ensuring accuracy in the comparison process. + - Error handling mechanisms are in place to manage potential errors that might occur during hash verification or the re-synchronization request process. + +#### Key Considerations: +- **Hash Verification:** The function verifies the received block hash (`hash`) against the calculated hash of the corresponding block data, ensuring data integrity. +- **Resynchronization:** In the event of a hash mismatch, the function proactively triggers a re-synchronization request for the specific block data, enabling the correction of potential inconsistencies. +- **Asynchronous Processing:** Asynchronous operations, facilitated through promises, allow the function to handle hash verification and re-synchronization requests efficiently and non-blocking. +- **Error Handling:** The function incorporates error handling mechanisms to address potential errors arising during hash verification or the re-synchronization process, enhancing the reliability of the synchronization mechanism. + +#### Workflow Summary: +1. **Hash Verification:** The function initiates hash verification for the received block hash (`hash`) associated with the specified block number (`block_n`) and node (`node_i`). +2. **Mismatch Detection:** If a hash mismatch is detected during verification, indicating a potential data inconsistency, the function takes corrective action. +3. **Re-Synchronization Request:** A re-synchronization request is triggered by adding the specific block number and its mismatched hash to the synchronization queue, enabling the source node (`node_i`) to send the correct block data for synchronization. +4. **Error Handling:** The function incorporates error handling mechanisms to manage any errors that might occur during hash verification or the re-synchronization request process, ensuring the reliability of the synchronization mechanism. + +The `checkBlockHash` function plays a crucial role in maintaining the integrity of blockchain data by promptly identifying and addressing hash mismatches. Its proactive approach to requesting re-synchronization ensures the consistency and accuracy of data across distributed nodes, contributing significantly to the stability and reliability of the blockchain network. + + +### Verifying Block Hashes: Understanding `verifyBlockHash` Function + +The `verifyBlockHash` function is a critical component of the blockchain synchronization process, ensuring data integrity by verifying the hash of a specific block against its stored hash value in the database. This function plays a fundamental role in maintaining the accuracy and consistency of blockchain data across distributed nodes. Here's an overview of its functionality and key considerations: + +#### Function Overview: +- **Function Name:** `verifyBlockHash(node_i, block_n, hash)` +- **Parameters:** + - **`node_i` (String):** Identifier of the node for which the block hash is being verified. + - **`block_n` (Integer):** Block number corresponding to the hash being verified. + - **`hash` (String):** Hash value of the block data received from the node (`node_i`). +- **Functionality:** + - The `verifyBlockHash` function compares the received hash (`hash`) against the stored hash value of the specified block number (`block_n`) for the given node (`node_i`). + - If the received hash matches the stored hash value, indicating data integrity, the function resolves the promise with `true`. + - If the received hash does not match the stored hash value or the specified block number is not found, indicating a hash mismatch, the function resolves the promise with `false`. + - In case of a hash mismatch, the `verifyBlockHash` function can trigger corrective actions, such as initiating a re-synchronization request for the specific block data. + +#### Key Considerations: +- **Hash Verification:** The function performs hash verification by comparing the received hash (`hash`) with the stored hash value of the specified block number in the database. +- **Data Integrity:** Successful hash verification ensures the integrity of the received block data, indicating that the data has not been tampered with during transmission. +- **Promise-Based:** The function is implemented as a Promise, allowing for asynchronous execution and seamless integration into other asynchronous processes within the blockchain synchronization mechanism. +- **Hash Mismatch Handling:** In the event of a hash mismatch, the function can be integrated with processes that handle re-synchronization requests or other corrective actions to resolve data inconsistencies. + +#### Workflow Summary: +1. **Hash Retrieval:** The function retrieves the stored hash value of the specified block number (`block_n`) for the given node (`node_i`) from the database. +2. **Hash Comparison:** The received hash (`hash`) is compared with the stored hash value. If they match, the data integrity is confirmed, and the function resolves the promise with `true`. +3. **Mismatch Detection:** If the received hash does not match the stored hash value or the specified block number is not found, indicating a hash mismatch, the function resolves the promise with `false`. +4. **Hash Mismatch Actions:** Depending on the application's logic, the function can be configured to trigger actions in response to hash mismatches, such as initiating re-synchronization requests or performing other corrective measures. + +The `verifyBlockHash` function is a foundational element in blockchain systems, ensuring the trustworthiness of data by verifying the authenticity of received block hashes. Its seamless integration with the synchronization process contributes to the overall reliability and security of blockchain networks. + + +### Setting Last Block Number: Understanding `setLastBlock` Function + +The `setLastBlock` function is a crucial component of the blockchain synchronization process, responsible for updating and tracking the last synchronized block number for a specific node. By setting the last block number, the function helps manage the progress of block synchronization and ensures that nodes remain up-to-date with the latest blockchain data. Here's a detailed overview of its functionality and key considerations: + +#### Function Overview: +- **Function Name:** `setLastBlock(node_i, block_n)` +- **Parameters:** + - **`node_i` (String):** Identifier of the node for which the last synchronized block number is being set. + - **`block_n` (Integer):** Block number indicating the last synchronized block for the specified node. +- **Functionality:** + - The `setLastBlock` function updates the last synchronized block number for the specified node (`node_i`) to the provided block number (`block_n`). + - Setting the last block number is essential for tracking the progress of blockchain synchronization, indicating up to which block the node's data is synchronized with the network. + - The function internally calls the `queueSync.last_block(node_i, block_n)` method, which manages the synchronization queue and initiates ordering processes after completing the synchronization of specific blocks. + +#### Key Considerations: +- **Progress Tracking:** By updating the last synchronized block number, the function allows the system to track the progress of blockchain synchronization for individual nodes. +- **Queue Management:** The function's integration with the `queueSync` module ensures effective management of block synchronization queues, enabling seamless handling of multiple nodes' synchronization processes. +- **Ordering Initiation:** After completing the synchronization of specific blocks, the function triggers the initiation of ordering processes, ensuring that the synchronized data is appropriately integrated into the blockchain network. + +#### Workflow Summary: +1. **Block Number Update:** The function receives the latest synchronized block number (`block_n`) for the specified node (`node_i`). +2. **Queue Management:** Internally, the function calls the `queueSync.last_block(node_i, block_n)` method, which manages the synchronization queue and completes the synchronization process for the specified block. +3. **Ordering Initiation:** After synchronizing the block, the function initiates ordering processes to ensure that the synchronized data is incorporated into the blockchain network seamlessly. + +The `setLastBlock` function plays a vital role in maintaining synchronization progress, ensuring that nodes remain current with the latest blockchain data. Its integration with queue management and ordering processes enhances the overall efficiency and reliability of blockchain synchronization within distributed networks. + + +### Sending Data for a Specific Block: Understanding `sendBlockData` Function + +The `sendBlockData` function plays a critical role in the blockchain synchronization process, enabling the transmission of specific block data from one node to another. This function is essential for ensuring that nodes within a distributed network are updated with the latest blockchain information. Here's a comprehensive overview of the `sendBlockData` function, outlining its functionality and key aspects: + +#### Function Overview: +- **Function Name:** `sendBlockData(node_i, block_n, ws)` +- **Parameters:** + - **`node_i` (String):** Identifier of the node from which block data is being sent. + - **`block_n` (Integer):** Block number indicating the specific block whose data is being transmitted. + - **`ws` (WebSocket):** WebSocket connection representing the recipient node to which the block data is sent. +- **Functionality:** + - The `sendBlockData` function initiates the process of sending block data (`block_n`) from a specified node (`node_i`) to a target node represented by the WebSocket connection (`ws`). + - The function begins by indicating the start of the data transmission for the specific block (`node_i`, `block_n`) to the recipient node using the `TYPE_.INDICATE_BLK` message type. + - Subsequently, the function queries the database to retrieve the data associated with the specified block (`block_n`) from the table named `${t_name}`, where `${t_name}` represents the table associated with the node (`node_i`). + - The retrieved block data is then transmitted to the recipient node (`ws`) using the `TYPE_.STORE_BACKUP_DATA` message type, allowing the recipient node to receive and store the blockchain data. + - Upon completing the data transmission, the function sends an indication to the recipient node, marking the end of the data transmission process for the specific block (`node_i`, `block_n`). + +#### Key Considerations: +- **Block Data Transmission:** The function facilitates the transmission of individual block data from one node to another, ensuring that nodes remain synchronized with the latest blockchain information. +- **Data Indication:** The function utilizes the `TYPE_.INDICATE_BLK` message type to indicate the start and end of the data transmission process, allowing recipient nodes to identify the boundaries of the transmitted data. +- **WebSocket Connection:** The `ws` parameter represents the WebSocket connection to the recipient node, enabling direct communication between nodes within the distributed network. + +#### Workflow Summary: +1. **Indicate Data Transmission:** The function initiates the data transmission process by sending an indication (`TYPE_.INDICATE_BLK`) to the recipient node (`ws`), marking the start of the transmission for the specific block (`node_i`, `block_n`). +2. **Retrieve Block Data:** The function queries the database to retrieve the block data associated with the specified block number (`block_n`) from the corresponding table (`${t_name}`) associated with the node (`node_i`). +3. **Transmit Block Data:** The retrieved block data is transmitted to the recipient node (`ws`) using the `TYPE_.STORE_BACKUP_DATA` message type, allowing the recipient node to receive and store the transmitted blockchain data. +4. **End Data Transmission:** After completing the data transmission, the function sends an indication (`TYPE_.INDICATE_BLK`) to the recipient node, marking the end of the transmission process for the specific block (`node_i`, `block_n`). + +The `sendBlockData` function serves as a pivotal component in maintaining blockchain synchronization, facilitating the seamless exchange of specific block data between nodes. Its integration with WebSocket connections and data indication mechanisms ensures efficient and reliable transmission of blockchain information within the distributed network. + + +### Ending Block Synchronization: Understanding `endBlockSync` Function + +The `endBlockSync` function plays a vital role in the blockchain synchronization process, specifically focusing on concluding the synchronization of a particular block between nodes. This function is crucial for ensuring that nodes within a distributed network successfully complete the synchronization of specific blocks, maintaining consistency across the blockchain. Here's a detailed overview of the `endBlockSync` function, highlighting its functionality and key aspects: + +#### Function Overview: +- **Function Name:** `endBlockSync(node_i, block_n)` +- **Parameters:** + - **`node_i` (String):** Identifier of the node for which block synchronization is being completed. + - **`block_n` (Integer):** Block number indicating the specific block for which synchronization is being finalized. +- **Functionality:** + - The `endBlockSync` function is responsible for concluding the synchronization process of a particular block (`block_n`) for the specified node (`node_i`). + - Upon invocation, the function communicates with the synchronization queue (`queueSync`) to mark the completion of the synchronization process for the specified block. + - The function ensures that the synchronization queue is updated, indicating that the block synchronization has been successfully finalized for the specified node and block number. + - By invoking `queueSync.end_block(node_i, block_n)`, the function triggers the necessary actions within the synchronization queue to manage the completion of the synchronization process. + +#### Key Considerations: +- **Block Synchronization Completion:** The primary purpose of the `endBlockSync` function is to indicate the successful completion of the synchronization process for a specific block (`block_n`) belonging to a particular node (`node_i`). +- **QueueSync Interaction:** The function interacts with the `queueSync` object, a critical component responsible for managing the synchronization queue, ensuring that the synchronization process progresses efficiently and accurately. +- **Synchronization Queue Management:** The function's invocation triggers internal mechanisms within the `queueSync` object, allowing it to handle the completion of the synchronization process, update internal states, and proceed with the next synchronization tasks if applicable. + +#### Workflow Summary: +1. **Synchronization Completion:** The function signifies the successful synchronization completion of a specific block (`block_n`) for the designated node (`node_i`). +2. **QueueSync Interaction:** The function communicates with the `queueSync` object, specifically invoking the `queueSync.end_block(node_i, block_n)` method to manage the completion of the synchronization process for the specified block. +3. **Internal Queue Handling:** Within the `queueSync` object, the completion of the synchronization process triggers internal mechanisms to handle the completed block, update internal states, and prepare for subsequent synchronization tasks if additional blocks are pending synchronization. + +The `endBlockSync` function serves as a crucial step in the synchronization process, ensuring that specific blocks are synchronized successfully and accurately between nodes within the distributed blockchain network. Its seamless interaction with the synchronization queue enables efficient management of block synchronization, contributing to the overall consistency and integrity of the blockchain network. + + +### Synchronization Indicator Function: Understanding `syncIndicator` + +The `syncIndicator` function plays a crucial role in the blockchain synchronization process, providing insights into the progress and completion of block synchronization between nodes. This function is responsible for indicating the start and end of the synchronization process for a specific block, enabling effective monitoring and management of blockchain synchronization. Here's a detailed overview of the `syncIndicator` function, highlighting its functionality and key aspects: + +#### Function Overview: +- **Function Name:** `syncIndicator(node_i, block_n, status, from)` +- **Parameters:** + - **`node_i` (String):** Identifier of the node associated with the synchronization process. + - **`block_n` (Integer):** Block number indicating the specific block involved in synchronization. + - **`status` (Boolean):** Status indicating whether the synchronization process is starting (`true`) or ending (`false`). + - **`from` (String):** Identifier of the node from which the synchronization data is received. +- **Functionality:** + - The `syncIndicator` function is responsible for logging synchronization events, specifically indicating the initiation (`status: true`) and completion (`status: false`) of the synchronization process for a specific block. + - When the `status` parameter is `true`, the function logs the start of the synchronization process, providing details such as the node identifier (`node_i`), block number (`block_n`), and the source node (`from`) from which the synchronization data is received. + - When the `status` parameter is `false`, signifying the end of the synchronization process, the function invokes the `endBlockSync` function to indicate the successful completion of block synchronization for the specified block (`block_n`) and node (`node_i`). + - The function's logging mechanism ensures that synchronization events are recorded, enabling real-time monitoring and analysis of blockchain synchronization activities. + +#### Key Considerations: +- **Synchronization Progress Logging:** The function logs synchronization events, providing valuable information about the progress of the synchronization process, including the involved nodes, block numbers, and synchronization status. +- **Dynamic Synchronization Monitoring:** By capturing synchronization events dynamically, the function allows developers and administrators to monitor synchronization activities in real-time, facilitating rapid response to synchronization issues or anomalies. +- **Integration with `endBlockSync`:** The function collaborates with the `endBlockSync` function, which is invoked when the synchronization process is successfully completed (`status: false`). This integration ensures that the synchronization queue is managed appropriately upon completion of synchronization activities. + +#### Workflow Summary: +1. **Synchronization Initiation:** When the `status` parameter is `true`, the function logs the start of the synchronization process, capturing details such as the node identifier, block number, and source node. +2. **Synchronization Completion:** When the `status` parameter is `false`, indicating the end of the synchronization process, the function invokes the `endBlockSync` function. This action signifies the successful completion of block synchronization for the specified block and node. +3. **Real-time Monitoring:** The function's logging mechanism enables real-time monitoring of synchronization events, allowing stakeholders to track the progress of blockchain synchronization activities, identify potential issues, and ensure the integrity of the distributed network. + +The `syncIndicator` function serves as a critical component in the blockchain synchronization process, offering essential insights into synchronization events and contributing to the overall reliability and stability of the blockchain network.