Improve transaction OpenAPI docs and align related schema descriptions

spec/core/finalization/routes/getFinalizationProofAtEpoch.yml

@@ -1,6 +1,6 @@
 tags:
   - Finalization routes
-summary: Get finalization proof
+summary: Get finalization proof at epoch
 description: Returns the finalization proof for the greatest block height associated with the given finalization epoch.
 operationId: getFinalizationProofAtEpoch
 parameters:

spec/core/finalization/routes/getFinalizationProofAtHeight.yml

@@ -1,6 +1,6 @@
 tags:
   - Finalization routes
-summary: Get finalization proof
+summary: Get finalization proof at height
 description: Returns the finalization proof for the block at the given height.
 operationId: getFinalizationProofAtHeight
 parameters:

spec/core/network/routes/getNetworkInflationAtHeight.yml

@@ -1,6 +1,6 @@
 tags:
   - Network routes
-summary: Returns the inflation distribution data at specific height
+summary: Returns the inflation distribution data at a specific height
 description: |
   Retrieves network inflation parameters at a given block height.
 operationId: getNetworkInflationAtHeight

spec/core/network/routes/getRentalFees.yml

@@ -4,7 +4,7 @@ summary: Get rental fees information
 description: |
   Returns the estimated effective rental fees for namespaces and mosaics.
   This endpoint is only available if the REST instance has access to catapult-server ``resources/config-network.properties`` file.
-  To activate this feature, add the setting "network.propertiesFilePath" in the configuration file (rest/resources/rest.json).
+  To activate this feature, add the setting ``network.propertiesFilePath`` in the configuration file (``rest/resources/rest.json``).
 operationId: getRentalFees
 responses:
   "200":

spec/core/network/routes/getTransactionFees.yml

@@ -2,8 +2,8 @@ tags:
   - Network routes
 summary: Get transaction fees information
 description: |
-  Returns the average, median, highest and lower fee multiplier over the last "numBlocksTransactionFeeStats".
-  The setting "numBlocksTransactionFeeStats" is adjustable via the configuration file (rest/resources/rest.json) per REST instance.
+  Returns the average, median, highest, and lowest fee multiplier over the last ``numBlocksTransactionFeeStats`` blocks.
+  The setting ``numBlocksTransactionFeeStats`` is adjustable in the REST configuration file (``rest.json``) per REST instance.
 operationId: getTransactionFees
 responses:
   "200":

spec/core/transaction/routes/announceTransaction.yml

@@ -2,21 +2,37 @@ tags:
   - Transaction routes
 summary: Announce a new transaction
 description: |
-  Announces a transaction to the network.
-  The [catbuffer library](https://github.com/symbol/symbol/tree/main/catbuffer)
-  defines the protocol to serialize and deserialize Symbol entities.
-  Catbuffers are integrated into [Symbol SDKs](https://docs.symbol.dev/sdk.html).
-  It's recommended to use SDKs instead of calling the API endpoint directly to announce transactions.
+  Broadcasts a signed transaction to the network through this node.
+
+  The request must contain the serialized transaction payload in hexadecimal form. Transactions are
+  normally created and signed client-side with a [Symbol SDK](https://docs.symbol.dev/sdk.html) and
+  then announced with this endpoint.
+
+  The [catbuffer library](https://github.com/symbol/symbol/tree/main/catbuffer) defines the binary
+  serialization format used by Symbol entities.
+
+  Acceptance by this node does not mean the transaction is already part of the blockchain. The
+  transaction still needs to be validated and confirmed by the network.
+
+  To verify the final result, query ``GET /transactionStatus/{hash}`` on the same node that received
+  the announce request. If that node drops the transaction before propagation, other nodes may not know
+  the transaction at all and can return ``404`` for the same hash. Transaction status availability is not guaranteed
+  indefinitely: failed statuses are stored in a capped collection and may be evicted as new entries arrive.
 operationId: announceTransaction
 requestBody:
   $ref: "../../../request_bodies/transactionPayload.yml"
 responses:
   "202":
-    description: success
+    description: Transaction accepted for processing and broadcast by the node.
     content:
       application/json:
         schema:
           $ref: "../schemas/AnnounceTransactionInfoDTO.yml"
+        examples:
+          success:
+            summary: Transaction packet pushed to the node
+            value:
+              message: "packet 9 was pushed to the network via /transactions"
   "400":
     $ref: "../../../responses/InvalidContent.yml"
   "409":

spec/core/transaction/routes/getConfirmedTransaction.yml

@@ -1,17 +1,66 @@
 tags:
   - Transaction routes
 summary: Get confirmed transaction information
-description: Returns confirmed transaction information given a transactionId or hash.
+description: |
+  Returns confirmed transaction information given a transaction ID assigned by the node or transaction hash.
+
+  Use this endpoint when you need on-chain transaction data (the transaction is already included in a block).
+  Use ``getUnconfirmedTransaction`` while the transaction is still in a node's unconfirmed pool, and
+  use ``getPartialTransaction`` for aggregate bonded transactions waiting for cosignatures.
 operationId: getConfirmedTransaction
 parameters:
   - $ref: "../../../parameters/path/transactionIdPath.yml"
 responses:
   "200":
-    description: success
+    description: Confirmed transaction information.
     content:
       application/json:
         schema:
           $ref: "../schemas/TransactionInfoDTO.yml"
+        examples:
+          aggregateTransaction:
+            summary: Example confirmed aggregate transaction
+            value:
+              meta:
+                height: "5299379"
+                hash: "399724B8F6EBA9327D84B52B39BD6B6B1CD07819DEEE633F3AB9BDC9A305B930"
+                merkleComponentHash: "215CA36FDB4FA94796DE931FAA68C97C855D69770CF0CAED0AC4D7E460580844"
+                index: 0
+                timestamp: "159214132791"
+                feeMultiplier: 128
+              transaction:
+                size: 368
+                signature: "0C34EA160F07070DAED62E734EAE734D1DFBD78499486A09561094551946DE3BAF79317AA000718724255C67BE..."
+                signerPublicKey: "B93B3931652DF080F1699F0EA14C6C760075785981C034AD4F435AC1EBEDA137"
+                version: 3
+                network: 104
+                type: 16961
+                maxFee: "47200"
+                deadline: "159221254067"
+                transactionsHash: "2C4946AB5EAD0224CBF43EE1432A06833243892CD27FE3B6CD0797E959CA5DC7"
+                cosignatures:
+                  - version: "0"
+                    signerPublicKey: "3AB7AF84CC38E4E112F840ABD31866BD83AD5BCE765F31F84601D35799B9FFF4"
+                    signature: "07BBD3BD1EBFDDE9B771F646278DEAEA245ED8FA66800169EE533377884F76816DEEDA8A8319EC838930DCC..."
+                transactions:
+                  - meta:
+                      height: "5299379"
+                      aggregateHash: "399724B8F6EBA9327D84B52B39BD6B6B1CD07819DEEE633F3AB9BDC9A305B930"
+                      aggregateId: "69CD60B02976BBB47C19E5D9"
+                      index: 0
+                      timestamp: "159214132791"
+                      feeMultiplier: 128
+                    transaction:
+                      signerPublicKey: "8AC8A6034897189C1C7F30CDD4FE88D881E2CE5F94E2580C390CCEAAD06362D3"
+                      version: 1
+                      network: 104
+                      type: 16724
+                      recipientAddress: "680D52CD378CDA123BFBBC54DB3CED5C4031473BF0B5EC02"
+                      mosaics:
+                        - id: "6BED913FA20223F8"
+                          amount: "11254000000"
+                    id: "69CD60B02976BBB47C19E5DA"
+              id: "69CD60B02976BBB47C19E5D9"
   "404":
     $ref: "../../../responses/ResourceNotFound.yml"
   "409":

spec/core/transaction/routes/getConfirmedTransactions.yml

@@ -1,20 +1,54 @@
 tags:
   - Transaction routes
-summary: Get confirmed trasactions information
-description: Returns confirmed transactions information for a given array of transactionIds.
+summary: Get confirmed transactions information
+description: |
+  Returns confirmed transactions for the list of identifiers in the request body.
+  Each request item can be either a transaction ID assigned by the node or a transaction hash.
+  Both values are returned by transaction retrieval and search endpoints, for example
+  ``GET /transactions/confirmed`` and ``GET /transactions/confirmed/{transactionId}``.
+
+  Use this endpoint when you need on-chain data for multiple transactions in one call.
+  Use ``getUnconfirmedTransactions`` for transactions still pending in a node pool, and
+  use ``getPartialTransactions`` for aggregate bonded transactions waiting for cosignatures.
 operationId: getConfirmedTransactions
 requestBody:
   $ref: "../../../request_bodies/transactionIds.yml"
 responses:
   "200":
-    description: success
+    description: Confirmed transaction information for the requested identifiers.
     content:
       application/json:
         schema:
           type: array
-          description: Array of transactions information.
+          description: Array of confirmed transaction entries.
           items:
             $ref: "../schemas/TransactionInfoDTO.yml"
+        examples:
+          default:
+            summary: Example confirmed transaction batch response
+            value:
+              - meta:
+                  height: "5299379"
+                  hash: "399724B8F6EBA9327D84B52B39BD6B6B1CD07819DEEE633F3AB9BDC9A305B930"
+                  merkleComponentHash: "215CA36FDB4FA94796DE931FAA68C97C855D69770CF0CAED0AC4D7E460580844"
+                  index: 0
+                  timestamp: "159214132791"
+                  feeMultiplier: 128
+                transaction:
+                  size: 368
+                  signature: "0C34EA160F07070DAED62E734EAE734D1DFBD78499486A09561094551946DE3BAF79317AA000718724255C67BE..."
+                  signerPublicKey: "B93B3931652DF080F1699F0EA14C6C760075785981C034AD4F435AC1EBEDA137"
+                  version: 3
+                  network: 104
+                  type: 16961
+                  maxFee: "47200"
+                  deadline: "159221254067"
+                  transactionsHash: "2C4946AB5EAD0224CBF43EE1432A06833243892CD27FE3B6CD0797E959CA5DC7"
+                  cosignatures:
+                    - version: "0"
+                      signerPublicKey: "3AB7AF84CC38E4E112F840ABD31866BD83AD5BCE765F31F84601D35799B9FFF4"
+                      signature: "07BBD3BD1EBFDDE9B771F646278DEAEA245ED8FA66800169EE533377884F76816DEEDA8A8319EC838930DC..."
+                id: "69CD60B02976BBB47C19E5D9"
   "400":
     $ref: "../../../responses/InvalidContent.yml"
   "409":

spec/core/transaction/routes/getPartialTransaction.yml

@@ -1,17 +1,64 @@
 tags:
   - Transaction routes
 summary: Get partial transaction information
-description: Returns partial transaction information given a transactionId or hash.
+description: |
+  Returns one partial transaction identified by the path value. Partial
+  transactions are aggregate bonded transactions waiting for the remaining cosignatures.
+
+  The path accepts either the transaction ID assigned by the node or the transaction hash.
+  Both values are returned by transaction retrieval and search endpoints, for example
+  ``GET /transactions/partial`` and ``GET /transactions/partial/{transactionId}``.
+
+  Use this endpoint for aggregate bonded transactions before they are fully cosigned.
+  Use ``getUnconfirmedTransaction`` for non-partial transactions that are in a node's unconfirmed pool,
+  and use ``getConfirmedTransaction`` once the transaction is confirmed on-chain.
 operationId: getPartialTransaction
 parameters:
   - $ref: "../../../parameters/path/transactionIdPath.yml"
 responses:
   "200":
-    description: success
+    description: Partial transaction information.
     content:
       application/json:
         schema:
           $ref: "../schemas/TransactionInfoDTO.yml"
+        examples:
+          aggregateBondedTransaction:
+            summary: Example partial aggregate bonded transaction
+            value:
+              meta:
+                height: "0"
+                hash: "D304E55AFE3CAC0D86F78A708570FADDF41490981D8242C043A12EDE90225409"
+                merkleComponentHash: "0000000000000000000000000000000000000000000000000000000000000000"
+                index: 0
+              transaction:
+                size: 264
+                signature: "C17FEC2639C3BEE110C11FA199AC96C29D41A502B3E90F0E879FD00AB0BEBC2BEA27CFD006CEA1E6E12AE4D3D149..."
+                signerPublicKey: "C46AA9E7F1953C8EC9E20CEE783378CE556C01648B3C9CC185FBA6ACFDB8AC9E"
+                version: 3
+                network: 152
+                type: 16961
+                maxFee: "43732"
+                deadline: "107964975712"
+                transactionsHash: "CDB1283FFAC65D16C0756EF55276C2715DEFC8606518FA60A2D6C3DC4AE902FB"
+                cosignatures: []
+                transactions:
+                  - meta:
+                      height: "0"
+                      aggregateHash: "D304E55AFE3CAC0D86F78A708570FADDF41490981D8242C043A12EDE90225409"
+                      aggregateId: "69CD0083C72A61F64A176E3A"
+                      index: 0
+                    transaction:
+                      signerPublicKey: "7E1BB23C2E24A699697383DA8EB28BED5986165EBA502BA8B66576531DB04503"
+                      version: 1
+                      network: 152
+                      type: 16724
+                      recipientAddress: "989D5AF7FB3149A8C9A34CBDDBB29714A4632239525161F6"
+                      mosaics:
+                        - id: "72C0212E67A08BCE"
+                          amount: "12000000"
+                    id: "69CD0083C72A61F64A176E3B"
+              id: "69CD0083C72A61F64A176E3A"
   "404":
     $ref: "../../../responses/ResourceNotFound.yml"
   "409":

spec/core/transaction/routes/getPartialTransactions.yml

@@ -1,20 +1,68 @@
 tags:
   - Transaction routes
-summary: Get partial trasactions information
-description: Returns partial transactions information for a given array of transactionIds.
+summary: Get information about partial transactions
+description: |
+  Returns partial transactions for the list of identifiers in the request body. Partial
+  transactions are aggregate bonded transactions waiting for the remaining cosignatures.
+
+  Each request item can be either a transaction ID assigned by the node or a transaction hash.
+  Both values are returned by transaction retrieval and search endpoints, for example
+  ``GET /transactions/partial`` and ``GET /transactions/partial/{transactionId}``.
+
+  Use this endpoint for aggregate bonded transactions that still wait for required cosignatures.
+  Use ``getUnconfirmedTransactions`` for non-partial pending transactions accepted by a node but not
+  yet included in a block, and use ``getConfirmedTransactions`` once transactions are confirmed on-chain.
 operationId: getPartialTransactions
 requestBody:
   $ref: "../../../request_bodies/transactionIds.yml"
 responses:
   "200":
-    description: success
+    description: Partial transaction information for the requested identifiers.
     content:
       application/json:
         schema:
           type: array
-          description: Array of transactions information.
+          description: Array of partial transaction entries.
           items:
             $ref: "../schemas/TransactionInfoDTO.yml"
+        examples:
+          default:
+            summary: Example partial transaction batch response
+            value:
+              - meta:
+                  height: "0"
+                  hash: "D304E55AFE3CAC0D86F78A708570FADDF41490981D8242C043A12EDE90225409"
+                  merkleComponentHash: "0000000000000000000000000000000000000000000000000000000000000000"
+                  index: 0
+                transaction:
+                  size: 264
+                  signature: "C17FEC2639C3BEE110C11FA199AC96C29D41A502B3E90F0E879FD00AB0BEBC2BEA27CFD006CEA1E6E12AE4D3D1..."
+                  signerPublicKey: "C46AA9E7F1953C8EC9E20CEE783378CE556C01648B3C9CC185FBA6ACFDB8AC9E"
+                  version: 3
+                  network: 152
+                  type: 16961
+                  maxFee: "43732"
+                  deadline: "107964975712"
+                  transactionsHash: "CDB1283FFAC65D16C0756EF55276C2715DEFC8606518FA60A2D6C3DC4AE902FB"
+                  cosignatures: []
+                id: "69CD0083C72A61F64A176E3A"
+              - meta:
+                  height: "0"
+                  hash: "E7FACE48AA997C6249D49C9BE4F30A0F8DB898BF266D578D06C8372CF0012305"
+                  merkleComponentHash: "0000000000000000000000000000000000000000000000000000000000000000"
+                  index: 0
+                transaction:
+                  size: 248
+                  signature: "416F363728A4F3BD89DF251138BDC4DD2B58B69C9C2CB0D9B2735E4643781023499F442CEB2D2796D4DA1A7CAB..."
+                  signerPublicKey: "FFEA4F971FA8A6DCF63B410F1FF2868A9A7E1EFFD8B73DFB39F190E324F23049"
+                  version: 3
+                  network: 152
+                  type: 16961
+                  maxFee: "45600"
+                  deadline: "107989381281"
+                  transactionsHash: "4C88E5297F38E158CAEFDB2674138E581553630F7CAA08C14920688F392F6557"
+                  cosignatures: []
+                id: "69CD5FAFC72A61F64A177DFC"
   "400":
     $ref: "../../../responses/InvalidContent.yml"
   "409":