feat(API): refactor merge rpc

[SeriousCoding789]

What does this PR do?

Implements #6927 — the gRPC counterpart of the HTTP servlet dedup in #6922.

RpcApiServiceOnSolidity and RpcApiServiceOnPBFT each re-declare the whole read surface as per-method delegations whose only job is to switch the per-thread read cursor:

@Override
public void getAccount(Account req, StreamObserver<Account> obs) {
  walletOnSolidity.futureGet(() -> rpcApiService.getWalletSolidityApi().getAccount(req, obs));
}

There are exactly 100 of these — 51 in the Solidity service, 49 in the PBFT one — spread over four inner service classes. This PR replaces them with a cursor-parameterized ServerInterceptor:

• Adds CursorServerInterceptor with SolidityCursorInterceptor / PbftCursorInterceptor. It brackets Listener.onHalfClose() — the callback gRPC runs a unary handler inline from — setting the cursor before and restoring it in a finally.
• The two cursor services now register the base service's DatabaseApi / WalletSolidityApi singletons directly, wrapped in ServerInterceptors.intercept(...). RpcApiServiceOnSolidity goes from 488 lines to 36, RpcApiServiceOnPBFT from 495 to 36.
• A second, independent axis of duplication inside RpcApiService itself: WalletSolidityApi (serving protocol.WalletSolidity) re-implements read handlers WalletApi (serving protocol.Wallet) already has. 41 of its 47 methods now delegate to the shared WalletApi singleton; the remaining 6 already routed through shared *Common / callContract helpers, so no duplicated handler body is left. Java is single-inheritance and gRPC generates one ImplBase per proto service, so both classes have to stay — only the bodies go.
• Fixes the double-close on the error path, which the dedup made visible. A handler that calls responseObserver.onError(...) and then falls through to responseObserver.onCompleted() closes the call twice; the second close() hits checkState(!closeCalled, "call already closed") in gRPC's ServerCallImpl and throws. RpcApiService had 32 handlers shaped that way on develop — 8 disappear with the duplicated WalletSolidityApi bodies, and the remaining 24 get an explicit return, the shape the file already used elsewhere. The file now has none.

10 files changed, +945 / −1267.

Why are these changes required?

A read handler currently lives in up to four places, so one RPC change has to be mirrored four times, and missing one makes the same RPC behave differently depending on which port a client hits.

That has already happened. Of the 41 handlers being dedup'd inside RpcApiService, 23 are byte-identical between the two copies on develop and 18 differ. Of those 18:

• 8 are hardening that only ever landed in WalletApi — it gained a return after responseObserver.onError(...) and WalletSolidityApi did not, so on the error path the copy serving the Solidity and PBFT ports falls through to onCompleted() and terminates the call twice (getMerkleTreeVoucherInfo, isSpend, scanAndMarkNoteByIvk, scanNoteByIvk, scanNoteByOvk, isShieldedTRC20ContractNoteSpent, scanShieldedTRC20NotesByIvk, scanShieldedTRC20NotesByOvk). The last two additionally have a BadItemException | ZksnarkException branch with logging that only WalletApi ever received.
• 7 are cosmetic — a parameter name, a temporary variable, line wrapping.
• 1 differs only in a log prefix.
• 2 (getBlockByNum, getBlockByNum2) drifted the other way: WalletSolidityApi has a num >= 0 guard WalletApi lacks.

None of that was written deliberately; it is what happens when the same handler exists four times.

Lining the two copies up also showed that the return hardening was never finished on WalletApi either — 24 more handlers in the same file still fall through — so this PR completes it rather than leaving the file in two states.

Behaviour differences vs develop

Method sets, per port. The base WalletSolidityApi (47 methods) and DatabaseApi (4) expose exactly the same methods before and after — only bodies changed.

Port	Before	After	Delta
HEAD (RpcApiService)	47 + 4	47 + 4	none
SOLIDITY	47 + 4	47 + 4	none
PBFT	45 + 4	47 + 4	+2

The PBFT port gains getPaginatedNowWitnessList and getTransactionInfoByBlockNum — the only two methods RpcApiServiceOnPBFT never mirrored from RpcApiServiceOnSolidity; they returned UNIMPLEMENTED there before. Both are ordinary reads and resolve against the PBFT snapshot like every other read on that port.

Handler bodies. Only three WalletApi bodies changed beyond the added returns:

• getBlockByNum / getBlockByNum2 adopt the solidity copy's num >= 0 guard. No response change — Wallet#getBlockByNum already catches the StoreException and returns null for a negative number, so both paths reach onNext(null); the guard only skips a futile store lookup and its log line.
• getAssetIssueByName drops the "FullNode " prefix from one logger.debug line, which was the only difference between the two copies.

Error paths. Every handler that used to emit onError followed by onCompleted now emits a single terminal event, on all three ports. Not visible to clients — onError had already closed the call with the error status and the second close() threw before sending anything; what goes away is one server-side IllegalStateException per failed call. Two groups:

• Fixed as a side effect of the dedup, on the SOLIDITY and PBFT ports: the 8 shielded handlers listed above. Worth noting these were not a rare corner — the first statement of the five sapling reads in Wallet is checkAllowShieldedTransactionApi(), and node.allowShieldedTransactionApi defaults to false, so on a default node every such call took the double-close path.
• Fixed explicitly, on all three ports: 17 handlers in WalletApi (getPaginatedNowWitnessList, getTransactionInfoByBlockNum, getDelegatedResourceV2, getDelegatedResourceAccountIndex, getDelegatedResourceAccountIndexV2, getCanDelegatedMaxSize, getCanWithdrawUnfreezeAmount, getAvailableUnfreezeCount, getBandwidthPrices, getEnergyPrices, getMemoFee, getNodeInfo, getMarketOrderByAccount, getMarketOrderById, getMarketOrderListByPair, getMarketPriceByPair, getMarketPairList) and 7 shared helpers reachable from both services (getBlockCommon, getRewardInfoCommon, getBrokerageInfoCommon, getBurnTrxCommon, getPendingSizeCommon, getTransactionFromPendingCommon, getTransactionListFromPendingCommon).

Cursor semantics are unchanged. Manager#setCursor still computes the headNum - pbftNum offset for PBFT, exactly as WalletOnPBFT.futureGet did.

Scope. gRPC only. WalletOnCursor / WalletOnSolidity / WalletOnPBFT stay, because the HTTP and JSON-RPC servlets still call futureGet; removing those is a separate change. Ports, switches, proto definitions and the server-level interceptor chain (rate limiter, api access, lite-fullnode filter, prometheus) are untouched.

This PR has been tested by:

• Unit Tests — 7 new tests plus two assertions added to the existing end-to-end suite, all passing. Each pins something that can actually go wrong:
  • CursorInterceptorScopeTest (2) drives interceptCall() on one thread and the returned listener's onHalfClose() on another — which is what gRPC's SerializingExecutor is free to do. An implementation that scoped the cursor around interceptCall fails here by construction rather than by luck. Also covers the finally reset when the handler throws.
  • CursorInterceptorServerTest (1) runs the production interceptor behind a real gRPC server and asserts the cursor is set and restored exactly once, on the handler's own thread. This is the end-to-end half: the whole design rests on gRPC running the handler inline from onHalfClose, and if that stops holding the cursor never reaches the read path and the port serves HEAD data with no error.
  • CursorInterceptorWiringTest (2) runs the real addService of both cursor services against a mock builder and asserts each shared read service is registered as an intercepted definition. Dropping ServerInterceptors.intercept leaves every other test green while the port silently serves HEAD, so this is the gRPC counterpart of CursorFilterInstallationTest.
  • RpcApiServiceErrorPathTest (2) drives every unary handler of WalletApi and WalletSolidityApi with collaborators that throw, and asserts none of them terminates the call more than once. Reverting the added returns makes it fail on getDelegatedResourceV2, getPendingSize and getBlock, so it reaches the shared *Common helpers as well.
  • RpcApiServicesTest — the existing suite drives all three ports end to end over 129 tests; it now also calls getPaginatedNowWitnessList and getTransactionInfoByBlockNum on the PBFT stub, pinning the one intentional behaviour change.
• Manual Testing

[waynercheung]

Reviewed 90db120. I did not find a production correctness regression in the audited synchronous read paths.

• [SHOULD] The branch conflicts with release_v4.8.3 in RpcApiServiceOnSolidity.java: #6999 modified the transaction2Extention helper that this PR removes. Resolve both conflict hunks in favor of this PR, dropping the release-branch side entirely (the transaction2Extention / block2Extention helpers, the old inner DatabaseApi / WalletSolidityApi classes, and their imports) while retaining this PR's shared-service registrations. Please rerun CI; the resolution will need review on the updated HEAD.
• [SHOULD] Please strengthen the cursor-wiring and checked-exception error-path tests as noted in the review threads.
• [DISCUSS] In #6927, we agreed to separate the missing-return fixes for independent backporting. Please confirm which release lines need these fixes and how they will be delivered if the changes remain combined.
• [SHOULD] Please add a compatibility/release note for getPaginatedNowWitnessList and getTransactionInfoByBlockNum on the PBFT port. They change from UNIMPLEMENTED to implemented responses, which may affect clients using that status to identify endpoint capabilities.

[SeriousCoding789]

Reviewed 90db120. I did not find a production correctness regression in the audited synchronous read paths.

• [SHOULD] The branch conflicts with release_v4.8.3 in RpcApiServiceOnSolidity.java: refactor(crypto): remove unused SM2 and SM3 #6999 modified the transaction2Extention helper that this PR removes. Resolve both conflict hunks in favor of this PR, dropping the release-branch side entirely (the transaction2Extention / block2Extention helpers, the old inner DatabaseApi / WalletSolidityApi classes, and their imports) while retaining this PR's shared-service registrations. Please rerun CI; the resolution will need review on the updated HEAD.
• [SHOULD] Please strengthen the cursor-wiring and checked-exception error-path tests as noted in the review threads.
• [DISCUSS] In [Feature] Deduplicate gRPC cursor services with a ServerInterceptor #6927, we agreed to separate the missing-return fixes for independent backporting. Please confirm which release lines need these fixes and how they will be delivered if the changes remain combined.
• [SHOULD] Please add a compatibility/release note for getPaginatedNowWitnessList and getTransactionInfoByBlockNum on the PBFT port. They change from UNIMPLEMENTED to implemented responses, which may affect clients using that status to identify endpoint capabilities.

All fixed, please help review again.

[waynercheung]

Re-reviewed 89c5584b50. All 11 PR files are unchanged from the locally validated 082d99b99b. The previous code-side findings are addressed, and CI is green. Mutation checks confirmed that the updated tests detect the previously missed wiring and checked-exception regressions.

Approving. The following follow-ups are non-blocking:

• [NIT] Please refresh the outdated diff/test counts in the PR description: 11 files, +892/-1264; RpcApiServicesTest: 119; CursorInterceptorScopeTest: 1; RpcApiServiceErrorPathTest: 3. Please also remove the reference to the nonexistent CursorFilterInstallationTest.
• [SHOULD] Please add an explicit compatibility note for the two PBFT additions, getPaginatedNowWitnessList and getTransactionInfoByBlockNum: clients relying on UNIMPLEMENTED to identify PBFT endpoints may need adjustment.
• [DISCUSS] Please confirm the backport decision for the missing-return fixes, including the target release lines if needed. If none require backporting, an explicit "no backport needed" is sufficient.