chore: change endpoint names (#281)

* chore: change endpoint names * chore: fixed fmt
atoma-network · Dec 12, 2024 · 893a486 · 893a486
1 parent 7623975
commit 893a486
Show file tree

Hide file tree

Showing 11 changed files with 100 additions and 25 deletions.
diff --git a/atoma-daemon/docs/openapi.yml b/atoma-daemon/docs/openapi.yml
@@ -13,7 +13,8 @@ paths:
     get:
       tags:
       - Almost filled stacks
-      summary: Retrieves all stacks that are filled above a specified fraction threshold for all registered nodes.
+      summary: List almost filled stacks
+      description: Retrieves all stacks that are filled above a specified fraction threshold for all registered nodes.
       operationId: almost_filled_stacks_fraction_get
       parameters:
       - name: fraction
@@ -38,8 +39,10 @@ paths:
     get:
       tags:
       - Almost filled stacks
-      summary: Retrieves all stacks that are filled above a specified fraction threshold for a specific node.
+      summary: List almost filled stacks for a specific node
       description: |-
+        Retrieves all stacks that are filled above a specified fraction threshold for a specific node.
+
         # Arguments
         * `daemon_state` - The shared state containing the state manager
         * `node_small_id` - The small ID of the node whose stacks should be retrieved
@@ -83,7 +86,8 @@ paths:
     get:
       tags:
       - Attestation disputes
-      summary: Retrieves all attestation disputes against the currently registered nodes.
+      summary: List attestation disputes against currently registered nodes
+      description: Retrieves all attestation disputes against the currently registered nodes.
       operationId: attestation_disputes_against_list
       responses:
         '200':
@@ -100,7 +104,8 @@ paths:
     get:
       tags:
       - Attestation disputes
-      summary: Retrieves all attestation disputes against a specific node.
+      summary: List attestation disputes against a specific node
+      description: Retrieves all attestation disputes against a specific node.
       operationId: attestation_disputes_against_get
       parameters:
       - name: id
@@ -125,7 +130,8 @@ paths:
     get:
       tags:
       - Attestation disputes
-      summary: Retrieves all attestation disputes initiated by the currently registered nodes.
+      summary: List attestation disputes initiated by currently registered nodes
+      description: Retrieves all attestation disputes initiated by the currently registered nodes.
       operationId: attestation_disputes_own_list
       responses:
         '200':
@@ -142,7 +148,8 @@ paths:
     get:
       tags:
       - Attestation disputes
-      summary: Retrieves all attestation disputes initiated by a specific node.
+      summary: List attestation disputes initiated by a specific node
+      description: Retrieves all attestation disputes initiated by a specific node.
       operationId: attestation_disputes_own_get
       parameters:
       - name: id
@@ -167,7 +174,8 @@ paths:
     post:
       tags:
       - Nodes
-      summary: Claims funds for completed stacks.
+      summary: Create claim funds transaction
+      description: Claims funds for completed stacks.
       operationId: nodes_claim_funds
       requestBody:
         content:
@@ -188,7 +196,8 @@ paths:
     post:
       tags:
       - Nodes
-      summary: Subscribes a node to a specific model.
+      summary: Create model subscription transaction
+      description: Subscribes a node to a specific model.
       operationId: nodes_model_subscribe
       requestBody:
         content:
@@ -209,7 +218,8 @@ paths:
     post:
       tags:
       - Nodes
-      summary: Registers a new node in the system.
+      summary: Create node registration transaction
+      description: Registers a new node in the system.
       operationId: nodes_register
       requestBody:
         content:
@@ -230,7 +240,8 @@ paths:
     post:
       tags:
       - Nodes
-      summary: Submits attestations for stack settlement.
+      summary: Create attestation proof transaction
+      description: Submits attestations for stack settlement.
       operationId: nodes_submit_attestations
       requestBody:
         content:
@@ -251,7 +262,8 @@ paths:
     post:
       tags:
       - Nodes
-      summary: Subscribes a node to a specific task.
+      summary: Create task subscription transaction
+      description: Subscribes a node to a specific task.
       operationId: nodes_task_subscribe
       requestBody:
         content:
@@ -293,7 +305,8 @@ paths:
     post:
       tags:
       - Nodes
-      summary: Updates an existing task subscription for a node.
+      summary: Modify task subscription
+      description: Updates an existing task subscription for a node.
       operationId: nodes_task_update_subscription
       requestBody:
         content:
@@ -314,7 +327,8 @@ paths:
     post:
       tags:
       - Nodes
-      summary: Attempts to settle stacks for a node.
+      summary: Create try settle stacks transaction
+      description: Attempts to settle stacks for a node.
       operationId: nodes_try_settle_stacks
       requestBody:
         content:
@@ -335,7 +349,8 @@ paths:
     get:
       tags:
       - Stacks
-      summary: Retrieves all claimed stacks for the currently registered node badges.
+      summary: List all claimed stacks for currently registered nodes
+      description: Retrieves all claimed stacks for the currently registered node badges.
       operationId: claimed_stacks_list
       responses:
         '200':
@@ -352,7 +367,8 @@ paths:
     get:
       tags:
       - Stacks
-      summary: Retrieves all claimed stacks for a specific node identified by its small ID.
+      summary: List all claimed stacks for a specific node
+      description: Retrieves all claimed stacks for a specific node identified by its small ID.
       operationId: claimed_stacks_get
       parameters:
       - name: id
@@ -377,7 +393,8 @@ paths:
     get:
       tags:
       - Stacks
-      summary: Retrieves all stacks associated with the currently registered node badges.
+      summary: List all stacks for currently registered nodes
+      description: Retrieves all stacks associated with the currently registered node badges.
       operationId: stacks_list
       responses:
         '200':
@@ -394,7 +411,8 @@ paths:
     get:
       tags:
       - Stacks
-      summary: Retrieves all stacks for a specific node identified by its small ID.
+      summary: List all stacks for a specific node
+      description: Retrieves all stacks for a specific node identified by its small ID.
       operationId: stacks_get
       parameters:
       - name: id
@@ -419,7 +437,8 @@ paths:
     get:
       tags:
       - Subscriptions
-      summary: Retrieves all node subscriptions for the currently registered node badges.
+      summary: List all subscriptions for currently registered nodes
+      description: Retrieves all node subscriptions for the currently registered node badges.
       operationId: subscriptions_list
       responses:
         '200':
@@ -438,7 +457,8 @@ paths:
     get:
       tags:
       - Subscriptions
-      summary: Retrieves all subscriptions for a specific node identified by its small ID.
+      summary: List all subscriptions for a specific node
+      description: Retrieves all subscriptions for a specific node identified by its small ID.
       operationId: subscriptions_get
       parameters:
       - name: id
@@ -463,7 +483,8 @@ paths:
     get:
       tags:
       - Tasks
-      summary: Retrieves all tasks from the state manager.
+      summary: List all tasks
+      description: Retrieves all tasks from the state manager.
       operationId: tasks_list
       responses:
         '200':

diff --git a/atoma-daemon/src/handlers/almost_filled_stacks.rs b/atoma-daemon/src/handlers/almost_filled_stacks.rs
@@ -19,6 +19,11 @@ pub const ALMOST_FILLED_STACKS_PATH: &str = "/almost_filled_stacks";
 )]
 pub(crate) struct AlmostFilledStacksOpenApi;
 
+//TODO: we should implement the following endpoints:
+// - GET /stacks - List all stacks. A filter `fraction` can be applied
+// - GET /stacks/nodes/:id - List all stacks for a specific node. A filter `fraction` can be applied
+// Move into stacks.rs
+
 /// Router for handling almost filled stacks endpoints
 ///
 /// Creates routes for:
@@ -36,6 +41,8 @@ pub fn almost_filled_stacks_router() -> Router<DaemonState> {
         )
 }
 
+/// List almost filled stacks
+///
 /// Retrieves all stacks that are filled above a specified fraction threshold for all registered nodes.
 #[utoipa::path(
     get,
@@ -71,6 +78,8 @@ pub async fn almost_filled_stacks_fraction_get(
     ))
 }
 
+/// List almost filled stacks for a specific node
+///
 /// Retrieves all stacks that are filled above a specified fraction threshold for a specific node.
 ///
 /// # Arguments

diff --git a/atoma-daemon/src/handlers/attestation_disputes.rs b/atoma-daemon/src/handlers/attestation_disputes.rs
@@ -24,6 +24,8 @@ pub const ATTESTATION_DISPUTES_PATH: &str = "/attestation_disputes";
 )]
 pub(crate) struct AttestationDisputesOpenApi;
 
+//TODO: this endpoint can be merged into one (I think) through filters
+
 /// Router for handling attestation disputes endpoints
 ///
 /// Creates routes for:
@@ -51,6 +53,8 @@ pub fn attestation_disputes_router() -> Router<DaemonState> {
         )
 }
 
+/// List attestation disputes against currently registered nodes
+///
 /// Retrieves all attestation disputes against the currently registered nodes.
 #[utoipa::path(
     get,
@@ -81,6 +85,8 @@ pub async fn attestation_disputes_against_list(
     ))
 }
 
+/// List attestation disputes against a specific node
+///
 /// Retrieves all attestation disputes against a specific node.
 #[utoipa::path(
     get,
@@ -109,6 +115,8 @@ pub async fn attestation_disputes_against_get(
     ))
 }
 
+/// List attestation disputes initiated by currently registered nodes
+///
 /// Retrieves all attestation disputes initiated by the currently registered nodes.
 #[utoipa::path(
     get,
@@ -139,6 +147,8 @@ pub async fn attestation_disputes_own_list(
     ))
 }
 
+/// List attestation disputes initiated by a specific node
+///
 /// Retrieves all attestation disputes initiated by a specific node.
 #[utoipa::path(
     get,

diff --git a/atoma-daemon/src/handlers/nodes.rs b/atoma-daemon/src/handlers/nodes.rs
@@ -90,6 +90,8 @@ pub fn nodes_router() -> Router<DaemonState> {
         )
 }
 
+/// Create node registration transaction
+///
 /// Registers a new node in the system.
 #[utoipa::path(
     post,
@@ -121,6 +123,8 @@ pub async fn nodes_register(
     Ok(Json(NodeRegistrationResponse { tx_digest }))
 }
 
+/// Create model subscription transaction
+///
 /// Subscribes a node to a specific model.
 #[utoipa::path(
     post,
@@ -163,6 +167,8 @@ pub async fn nodes_model_subscribe(
     Ok(Json(NodeModelSubscriptionResponse { tx_digest }))
 }
 
+/// Create task subscription transaction
+///
 /// Subscribes a node to a specific task.
 #[utoipa::path(
     post,
@@ -207,6 +213,8 @@ pub async fn nodes_task_subscribe(
     Ok(Json(NodeTaskSubscriptionResponse { tx_digest }))
 }
 
+/// Modify task subscription
+///
 /// Updates an existing task subscription for a node.
 #[utoipa::path(
     post,
@@ -251,6 +259,8 @@ pub async fn nodes_task_update_subscription(
     Ok(Json(NodeTaskUpdateSubscriptionResponse { tx_digest }))
 }
 
+//TODO: change to delete
+
 /// Unsubscribes a node from a specific task.
 #[utoipa::path(
     post,
@@ -291,6 +301,8 @@ pub async fn nodes_task_unsubscribe(
     Ok(Json(NodeTaskUnsubscriptionResponse { tx_digest }))
 }
 
+/// Create try settle stacks transaction
+///
 /// Attempts to settle stacks for a node.
 #[utoipa::path(
     post,
@@ -354,6 +366,8 @@ pub async fn nodes_try_settle_stacks(
     Ok(Json(NodeTrySettleStacksResponse { tx_digests }))
 }
 
+/// Create attestation proof transaction
+///
 /// Submits attestations for stack settlement.
 #[utoipa::path(
     post,
@@ -465,6 +479,8 @@ pub async fn nodes_submit_attestations(
     Ok(Json(NodeAttestationProofResponse { tx_digests }))
 }
 
+/// Create claim funds transaction
+///
 /// Claims funds for completed stacks.
 #[utoipa::path(
     post,

diff --git a/atoma-daemon/src/handlers/stacks.rs b/atoma-daemon/src/handlers/stacks.rs
@@ -19,6 +19,8 @@ pub const STACKS_PATH: &str = "/stacks";
 )]
 pub(crate) struct StacksOpenApi;
 
+//TODO: all of these endpoints should be deleted and replaced with the ones I suggested in the TODO of almost_filled_stacks.rs. If necessary, we can add additional filters to the endpoints to accomplish the functionality present in these endpoints.
+
 /// Router for handling stack-related endpoints
 ///
 /// This function sets up the routing for various stack-related operations,
@@ -33,6 +35,8 @@ pub fn stacks_router() -> Router<DaemonState> {
         .route("/claimed_stacks/:id", get(claimed_stacks_get))
 }
 
+/// List all stacks for currently registered nodes
+///
 /// Retrieves all stacks associated with the currently registered node badges.
 #[utoipa::path(
     get,
@@ -63,6 +67,8 @@ pub async fn stacks_list(
     ))
 }
 
+/// List all stacks for a specific node
+///
 /// Retrieves all stacks for a specific node identified by its small ID.
 #[utoipa::path(
     get,
@@ -91,6 +97,8 @@ pub async fn stacks_get(
     ))
 }
 
+/// List all claimed stacks for currently registered nodes
+///
 /// Retrieves all claimed stacks for the currently registered node badges.
 #[utoipa::path(
     get,
@@ -121,6 +129,8 @@ pub async fn claimed_stacks_list(
     ))
 }
 
+/// List all claimed stacks for a specific node
+///
 /// Retrieves all claimed stacks for a specific node identified by its small ID.
 #[utoipa::path(
     get,