docs: update openapi spec (#2618)

ninabarbakadze · web-flow · commit 1969636fe460 · 2025-11-03T09:56:47.000-05:00
Fixes #1406 <img width="1445" height="604" alt="Screenshot 2025-11-03 at 09 27 28" src="https://github.com/user-attachments/assets/a439e41a-a2ca-4224-993d-e8cf70d53d3b" /> <img width="1433" height="790" alt="Screenshot 2025-11-03 at 09 27 37" src="https://github.com/user-attachments/assets/7c3c8720-9713-4aa0-be30-6e5fb3601444" />
diff --git a/rpc/core/tx.go b/rpc/core/tx.go
@@ -265,7 +265,12 @@ func (env *Environment) TxStatus(ctx *rpctypes.Context, hash []byte) (*ctypes.Re
 		return &ctypes.ResultTxStatus{Status: TxStatusRejected, ExecutionCode: code, Error: log}, nil
 	}
 
-	// If the tx is not in the mempool, evicted, or committed, return unknown
+	// If the tx is not in the mempool, evicted, or committed, return unknown.
+	// This can happen in the following cases:
+	// - Tx was never submitted to this node
+	// - Tx was evicted/rejected and has expired from the cache
+	// - Tx was submitted to a different node and not yet propagated
+	// - Tx is invalid and was immediately rejected without caching
 	return &ctypes.ResultTxStatus{Status: TxStatusUnknown}, nil
 }
 
diff --git a/rpc/core/types/responses.go b/rpc/core/types/responses.go
@@ -267,15 +267,30 @@ type ResultSignedBlock struct {
 // ResultTxStatus represents the status of a transaction during its life cycle.
 // It contains info to locate a tx in a committed block as well as its execution code, log if it fails and status.
 type ResultTxStatus struct {
-	Height        int64    `json:"height"`
-	Index         uint32   `json:"index"`
-	ExecutionCode uint32   `json:"execution_code"`
-	Error         string   `json:"error"`
-	Status        string   `json:"status"`
-	Codespace     string   `json:"codespace,omitempty"`
-	GasWanted     int64    `json:"gas_wanted,omitempty"`
-	GasUsed       int64    `json:"gas_used,omitempty"`
-	Signers       []string `json:"signers,omitempty"`
+	// Height is the block height where the transaction was committed. Only populated for COMMITTED status.
+	Height int64 `json:"height"`
+	// Index is the index of the transaction in the block. Only populated for COMMITTED status.
+	Index uint32 `json:"index"`
+	// ExecutionCode is the ABCI code returned by the application (0 = success, non-zero = error).
+	// Populated for REJECTED and COMMITTED statuses.
+	ExecutionCode uint32 `json:"execution_code"`
+	// Error contains the error message if the transaction failed. Populated for REJECTED and failed COMMITTED transactions.
+	Error string `json:"error"`
+	// Status represents the current state of the transaction. Possible values:
+	// - UNKNOWN: Transaction not found (never submitted, expired from cache, or submitted to different node)
+	// - PENDING: Transaction is in the mempool awaiting inclusion
+	// - EVICTED: Transaction was removed from mempool due to space constraints
+	// - REJECTED: Transaction was rejected by the application (e.g., during recheck)
+	// - COMMITTED: Transaction was included in a block
+	Status string `json:"status"`
+	// Codespace is the ABCI codespace for the error. Only populated for failed transactions.
+	Codespace string `json:"codespace,omitempty"`
+	// GasWanted is the maximum gas requested by the transaction. Only populated for COMMITTED status.
+	GasWanted int64 `json:"gas_wanted,omitempty"`
+	// GasUsed is the actual gas consumed during execution. Only populated for COMMITTED status.
+	GasUsed int64 `json:"gas_used,omitempty"`
+	// Signers contains the list of addresses that signed the transaction. Only populated for COMMITTED status.
+	Signers []string `json:"signers,omitempty"`
 }
 
 type ResultDataCommitment struct {
diff --git a/rpc/openapi/openapi.yaml b/rpc/openapi/openapi.yaml
@@ -1131,6 +1131,46 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
+  /tx_status:
+    get:
+      summary: Get transaction status by hash
+      operationId: tx_status
+      parameters:
+        - in: query
+          name: hash
+          description: Transaction hash to query
+          required: true
+          schema:
+            type: string
+            example: "145c8332ce4cbd96b78605e1a6fcefda8d29750870b4bec653795b99d995de11"
+      tags:
+        - Tx
+      description: |
+        Get the status of a transaction by its hash. This endpoint provides information
+        about a transaction's current state in its lifecycle.
+
+        The possible status values are:
+        - **UNKNOWN**: Transaction is not found anywhere (not in mempool, not evicted, not committed)
+        - **PENDING**: Transaction is currently in the mempool awaiting inclusion in a block
+        - **EVICTED**: Transaction was removed from the mempool (e.g., due to mempool being full)
+        - **REJECTED**: Transaction was rejected by the application (e.g., during recheck after a block)
+        - **COMMITTED**: Transaction has been included in a block
+
+        For REJECTED transactions, the response includes the execution code and error message.
+        For COMMITTED transactions, the response includes block height, index, execution details, gas usage, and signers.
+      responses:
+        "200":
+          description: Transaction status information
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TxStatusResponse"
+        "500":
+          description: Error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
 
 components:
   schemas:
@@ -2397,6 +2437,75 @@ components:
               example: "5wHwYl3uCkaoo2GaChQmSIu8hxpJxLcCuIi8fiHN4TMwrRIU/Af1cEG7Rcs/6LjTl7YjRSymJfYaFAoFdWF0b20SCzE0OTk5OTk1MDAwEhMKDQoFdWF0b20SBDUwMDAQwJoMGmoKJuta6YchAwswBShaB1wkZBctLIhYqBC3JrAI28XGzxP+rVEticGEEkAc+khTkKL9CDE47aDvjEHvUNt+izJfT4KVF2v2JkC+bmlH9K08q3PqHeMI9Z5up+XMusnTqlP985KF+SI5J3ZOIhhNYWRlIGJ5IENpcmNsZSB3aXRoIGxvdmU="
           type: object
 
+    TxStatusResponse:
+      type: object
+      required:
+        - "jsonrpc"
+        - "id"
+        - "result"
+      properties:
+        jsonrpc:
+          type: string
+          example: "2.0"
+        id:
+          type: integer
+          example: 0
+        result:
+          required:
+            - "status"
+          properties:
+            height:
+              type: string
+              example: "12345"
+              description: "Block height where the transaction was included (only for COMMITTED status)"
+            index:
+              type: integer
+              example: 0
+              description: "Index of the transaction within the block (only for COMMITTED status)"
+            execution_code:
+              type: integer
+              example: 0
+              description: "Execution code from the application (0 means success, non-zero means failure)"
+            error:
+              type: string
+              example: ""
+              description: "Error message if the transaction failed (for REJECTED or failed COMMITTED transactions)"
+            status:
+              type: string
+              enum:
+                - "UNKNOWN"
+                - "PENDING"
+                - "EVICTED"
+                - "REJECTED"
+                - "COMMITTED"
+              example: "COMMITTED"
+              description: |
+                Current status of the transaction:
+                - UNKNOWN: Not found in mempool, cache, or blockchain
+                - PENDING: Currently in the mempool awaiting inclusion in a block
+                - EVICTED: Removed from mempool due to space constraints/priority
+                - REJECTED: Rejected by the application (during recheck)
+                - COMMITTED: Included in a block
+            codespace:
+              type: string
+              example: "sdk"
+              description: "ABCI codespace for the error (only present if execution failed)"
+            gas_wanted:
+              type: string
+              example: "200000"
+              description: "Gas requested by the transaction (only for COMMITTED status)"
+            gas_used:
+              type: string
+              example: "85000"
+              description: "Gas actually used by the transaction (only for COMMITTED status)"
+            signers:
+              type: array
+              items:
+                type: string
+              example: ["celestia1abc...", "celestia1def..."]
+              description: "List of signer addresses (only for COMMITTED status)"
+          type: object
+
     ABCIInfoResponse:
       type: object
       required:

Original file line number	Diff line number	Diff line change
`@@ -265,7 +265,12 @@ func (env Environment) TxStatus(ctx rpctypes.Context, hash []byte) (*ctypes.Re`
`265`	`265`	`return &ctypes.ResultTxStatus{Status: TxStatusRejected, ExecutionCode: code, Error: log}, nil`
`266`	`266`	`}`
`267`	`267`
`268`		`- // If the tx is not in the mempool, evicted, or committed, return unknown`
	`268`	`+ // If the tx is not in the mempool, evicted, or committed, return unknown.`
	`269`	`+ // This can happen in the following cases:`
	`270`	`+ // - Tx was never submitted to this node`
	`271`	`+ // - Tx was evicted/rejected and has expired from the cache`
	`272`	`+ // - Tx was submitted to a different node and not yet propagated`
	`273`	`+ // - Tx is invalid and was immediately rejected without caching`
`269`	`274`	`return &ctypes.ResultTxStatus{Status: TxStatusUnknown}, nil`
`270`	`275`	`}`
`271`	`276`