• Fix single-element JSON-RPC batch requests returning wrong response shape
• Detect batch requests by checking for [ before unmarshaling, not just message count
• Extend UTXO response fix to handle batch arrays, preserving error:null and stripping jsonrpc
  field
• Add comprehensive tests for batch detection and UTXO response formatting

Add batch detection flag to JSON-RPC parser

• Add ParseJsonRPCMsgWithBatchFlag() function that detects batch requests by checking for [
 before unmarshaling
• Returns tuple of messages, isBatch flag, and error to distinguish single objects from
 single-element arrays
• Refactor ParseJsonRPCMsg() to delegate to new function for backward compatibility
• Simplify error handling by checking batch indicator upfront

protocol/chainlib/chainproxy/rpcInterfaceMessages/jsonRPCMessage.go

Test batch detection with comprehensive cases

• Add TestParseJsonRPCMsgWithBatchFlag() with 7 test cases covering single objects, single-element
 arrays, multi-element arrays, empty arrays, missing IDs, and invalid JSON
• Test critical case: single-element batch [{...}] must be detected as batch to receive array
 response
• Verify error handling for both single and batch JSON parsing failures

protocol/chainlib/chainproxy/rpcInterfaceMessages/jsonRPCMessage_test.go

Extend UTXO response fix to handle batch arrays

• Rename checkBTCResponseAndFixReply() to checkUTXOResponseAndFixReply() for clarity
• Add isUTXOFamily() helper to check if chain is BTC, BTCT, LTC, LTCT, DOGE, DOGET, BCH, or BCHT
• Extend function to handle both single responses and batch (array) responses
• Add convertToUTXOResponse() helper that strips jsonrpc field and preserves error field for
 JSON-RPC 1.0 compatibility
• Process batch arrays by converting each element and marshaling back to array format

protocol/chainlib/common.go

Description

ParseJsonRPCMsgWithBatchFlag() checks only data[0]=='[' (despite the comment claiming “first
non-whitespace byte”) and removed the prior “try batch on single unmarshal failure” behavior, so a
valid batch like " \n[{...}]" will now error instead of parsing. This rejects otherwise-valid
JSON-RPC batch requests and can break clients that pretty-print or prepend whitespace.

Code

protocol/chainlib/chainproxy/rpcInterfaceMessages/jsonRPCMessage.go[R175-192]

+func ParseJsonRPCMsgWithBatchFlag(data []byte) (msgRet []JsonrpcMessage, isBatch bool, err error) {
+	// Check if the data is a JSON array (batch request) by looking at the first non-whitespace byte.
+	// This must be done before unmarshaling because json.Unmarshal into a single struct may
+	// silently succeed on a single-element array, losing the batch context.
+	isBatch = len(data) > 0 && data[0] == '['
+	if isBatch {
+		var batch []JsonrpcMessage
+		err = json.Unmarshal(data, &batch)
+		if err != nil {
+			return nil, true, err
+		}
+		return batch, true, nil
+	}
+
  var msg JsonrpcMessage
  err = json.Unmarshal(data, &msg)
  if err != nil {
-		// we failed unmarshaling
-		// try to parse a batch
-		var batch []JsonrpcMessage
-		errBatch := json.Unmarshal(data, &batch)
-		if errBatch != nil {
-			// failed parsing both as batch and jsonrpc return the first unmarshal error, unless the first character is "["
-			if len(data) > 0 && data[0] == '[' {
-				return nil, errBatch
-			}
-			return nil, err
-		}
-		return batch, nil
+		return nil, false, err

Evidence

The new implementation sets isBatch based on the first byte only and, when isBatch is false, returns
the single-message unmarshal error without attempting to parse as a batch, so any batch not starting
at byte 0 with '[' (e.g., leading whitespace/BOM) will fail.

protocol/chainlib/chainproxy/rpcInterfaceMessages/jsonRPCMessage.go[171-197]
protocol/chainlib/jsonRPC.go[99-114]
protocol/chainlib/tendermintRPC.go[104-116]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`ParseJsonRPCMsgWithBatchFlag` decides `isBatch` via `data[0] == '['` and, if false, it tries only the single-object unmarshal and returns that error. Valid JSON-RPC batch payloads with leading whitespace/newlines (or UTF-8 BOM) will therefore be rejected.
### Issue Context
The function comment explicitly says “first non-whitespace byte”, but the code does not implement that. Prior behavior also attempted to parse as batch on single-object unmarshal failure; the new code no longer does.
### Fix Focus Areas
- protocol/chainlib/chainproxy/rpcInterfaceMessages/jsonRPCMessage.go[175-197]
### Expected fix
- Determine batch-ness from the first *non-whitespace* byte (e.g., `trimmed := bytes.TrimSpace(data)`; optionally strip BOM).
- Additionally (or alternatively), restore a safe fallback: if single-object unmarshal fails, try unmarshaling into `[]JsonrpcMessage` and set `isBatch=true` when that succeeds.
- Add a unit test for leading-whitespace batch inputs (e.g. `"\n  [{...}]"`).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

TendermintChainParser.ParseMsg now routes single-element JSON arrays through the batch path
(msgsLength==1 && !isBatch), but earliestRequestedBlock is only computed when msgsLength>1, so
single-element batches keep earliestRequestedBlock=spectypes.LATEST_BLOCK (-2). This makes
RequestedBlock() report earliest=-2 and can incorrectly disable archive routing for historical-block
requests sent as single-element batches.

Code

protocol/chainlib/tendermintRPC.go[R250-253]

+	if msgsLength == 1 && !isBatch {
  	tenderMsg := rpcInterfaceMessages.TendermintrpcMessage{JsonrpcMessage: msgs[0], Path: ""}
  	if !isJsonrpc {
  		tenderMsg.Path = urlPath // add path

Evidence

With the new && !isBatch condition, a single-element batch (msgsLength==1 and isBatch==true)
falls into the batch message container. But since CompareRequestedBlockInBatch is gated by
msgsLength > 1, earliestRequestedBlock remains initialized to LATEST_BLOCK (-2). Because
baseChainMessageContainer.RequestedBlock returns earliestRequestedBlock when it’s non-zero, the
archive rule sees a negative earliest (treated as “latest/not archive”) and may misroute historical
queries.

protocol/chainlib/tendermintRPC.go[151-155]
protocol/chainlib/tendermintRPC.go[244-262]
protocol/chainlib/chain_message.go[121-127]
protocol/chainlib/extensionslib/archive_parser_rule.go[23-31]
x/spec/types/types.go[28-33]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
After introducing `isBatch`, single-element JSON arrays are treated as batch requests in Tendermint parsing. However, `earliestRequestedBlock` is not updated for `msgsLength==1`, so batch messages can carry `earliestRequestedBlock = spectypes.LATEST_BLOCK (-2)`, which breaks downstream routing logic that relies on `RequestedBlock()`.
### Issue Context
- `earliestRequestedBlock` is initialized to `spectypes.LATEST_BLOCK`.
- `CompareRequestedBlockInBatch` is only called when `msgsLength > 1`.
- For `msgsLength == 1 && isBatch == true`, code uses `newBatchChainMessage(... earliestRequestedBlock ...)`.
### Fix Focus Areas
- protocol/chainlib/tendermintRPC.go[151-155]
- protocol/chainlib/tendermintRPC.go[244-262]
### Expected fix
Implement one of:
- Update earliest/latest tracking for batch requests regardless of size (e.g., call `CompareRequestedBlockInBatch` when `isBatch` is true, not only when `msgsLength>1`).
- Or, right before building the batch message, add a special-case: if `isBatch && msgsLength == 1`, set `earliestRequestedBlock = latestRequestedBlock`.
Add a unit/integration test for a single-element Tendermint JSON-RPC batch that requests a historical block and assert `RequestedBlock()` earliest is not `LATEST_BLOCK`.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

The newly added test function name does not follow the required TestComponent_Scenario convention,
which reduces consistency and discoverability across the test suite. This violates the repository’s
standard test naming requirement.

Code

protocol/chainlib/chainproxy/rpcInterfaceMessages/jsonRPCMessage_test.go[160]

+func TestParseJsonRPCMsgWithBatchFlag(t *testing.T) {

Evidence

PR Compliance ID 4 requires new/updated tests to follow the TestComponent_Scenario naming
convention. The added test is named TestParseJsonRPCMsgWithBatchFlag without a scenario suffix.

AGENTS.md
protocol/chainlib/chainproxy/rpcInterfaceMessages/jsonRPCMessage_test.go[160-160]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new test name does not follow the required `TestComponent_Scenario` naming convention.
## Issue Context
Repository compliance requires consistent test naming for maintainability and searchability.
## Fix Focus Areas
- protocol/chainlib/chainproxy/rpcInterfaceMessages/jsonRPCMessage_test.go[160-160]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

The newly added test cases are implemented as a sequence of t.Run blocks rather than a
table-driven test structure, which the repository expects when multiple similar scenarios are being
validated. This reduces maintainability as new scenarios are added.

Code

protocol/chainlib/common_test.go[R398-455]

+func TestCheckUTXOResponseAndFixReply(t *testing.T) {
+	t.Run("single_response_preserves_error_null", func(t *testing.T) {
+		// BTC-family nodes return "error":null; the relay pipeline uses omitempty which strips it
+		input := `{"jsonrpc":"2.0","id":"1","result":"abc","error":null}`
+		result := checkUTXOResponseAndFixReply("DOGE", []byte(input))
+		// Should preserve error:null and strip jsonrpc (BTC uses JSON-RPC 1.0)
+		var parsed map[string]interface{}
+		require.NoError(t, json.Unmarshal([]byte(result), &parsed))
+		_, hasError := parsed["error"]
+		require.True(t, hasError, "error field must be present (even when null)")
+		_, hasJsonrpc := parsed["jsonrpc"]
+		require.False(t, hasJsonrpc, "jsonrpc field should be stripped for BTC-family chains")
+	})
+
+	t.Run("batch_response_preserves_error_null", func(t *testing.T) {
+		// Multi-element batch: relay pipeline reconstructs with jsonrpc:"2.0" and omitempty on error
+		input := `[{"jsonrpc":"2.0","id":"1","result":"hash1"},{"jsonrpc":"2.0","id":"2","result":"hash2"}]`
+		result := checkUTXOResponseAndFixReply("DOGE", []byte(input))
+		var parsed []map[string]interface{}
+		require.NoError(t, json.Unmarshal([]byte(result), &parsed))
+		require.Len(t, parsed, 2)
+		for i, elem := range parsed {
+			_, hasError := elem["error"]
+			require.True(t, hasError, "batch element %d must have error field", i)
+			_, hasJsonrpc := elem["jsonrpc"]
+			require.False(t, hasJsonrpc, "batch element %d should not have jsonrpc field", i)
+		}
+	})
+
+	t.Run("single_element_batch_response", func(t *testing.T) {
+		// Single-element batch must stay as array
+		input := `[{"jsonrpc":"2.0","id":"1773768178254-0","result":"23699c7e"}]`
+		result := checkUTXOResponseAndFixReply("DOGE", []byte(input))
+		var parsed []map[string]interface{}
+		require.NoError(t, json.Unmarshal([]byte(result), &parsed), "single-element batch must remain an array")
+		require.Len(t, parsed, 1)
+		require.Equal(t, "1773768178254-0", parsed[0]["id"])
+		_, hasError := parsed[0]["error"]
+		require.True(t, hasError, "error field must be present")
+		_, hasJsonrpc := parsed[0]["jsonrpc"]
+		require.False(t, hasJsonrpc, "jsonrpc field should be stripped")
+	})
+
+	t.Run("non_btc_chain_passthrough", func(t *testing.T) {
+		input := `{"jsonrpc":"2.0","id":1,"result":"abc"}`
+		result := checkUTXOResponseAndFixReply("ETH1", []byte(input))
+		require.Equal(t, input, result, "non-BTC chains should pass through unchanged")
+	})
+
+	t.Run("btc_with_actual_error", func(t *testing.T) {
+		input := `{"id":"1","error":{"code":-8,"message":"Block height out of range"},"result":null}`
+		result := checkUTXOResponseAndFixReply("BTC", []byte(input))
+		var parsed map[string]interface{}
+		require.NoError(t, json.Unmarshal([]byte(result), &parsed))
+		errorField := parsed["error"]
+		require.NotNil(t, errorField, "error field must be preserved when not null")
+	})
+}

Evidence

PR Compliance ID 4 requires table-driven tests where appropriate and standard naming. This change
adds multiple closely related scenarios as separate t.Run blocks inside one test function rather
than a table ([]struct{...}) iterated over.

AGENTS.md
protocol/chainlib/common_test.go[398-455]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`TestCheckUTXOResponseAndFixReply` adds multiple scenario checks but is not structured as a table-driven test.
## Issue Context
Table-driven tests make it easier to add new scenarios and keep assertions uniform across similar inputs/outputs.
## Fix Focus Areas
- protocol/chainlib/common_test.go[398-455]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.