rpc: RPC handlers return codes.Unknown for predictable validation/lookup errors

[darioAnongba]

Problem

Most tapd RPC handlers return plain fmt.Errorf / wrapped errors rather than status.Error(codes.X, ...). gRPC then surfaces these as codes.Unknown, leaving clients with no programmatic way to distinguish bad input from a missing resource from an internal failure — the error string is the only signal.

Caught while wiring typed errors through tap-sdk's REST transport (lightninglabs/tap-sdk#80). REST and gRPC now agree on the code, but that agreement is trivially Unknown == Unknown for every case we tried:

RPC	Input	Actual	Expected
DecodeAddr	"not-a-tap-addr"	Unknown: unable to decode addr: address: invalid bech32m string	InvalidArgument
DecodeProof	[0x00, 0x01]	Unknown: invalid raw proof, could not identify decoding format	InvalidArgument
ExportProof	zero asset_id + zero script_key	Unknown: invalid script key: ... x coordinate 0x00..00 is not on the secp256k1 curve	InvalidArgument (bad key) or NotFound (missing proof)

Why it matters

SDK callers (Go, tap-sdk REST, any grpc-gateway client) want to branch on the error type — retry on Unavailable, surface InvalidArgument to the user, treat NotFound as a non-error, etc. Today they have to string-match, which is fragile and locale-sensitive.

Proposal

Audit the RPC surface and replace plain fmt.Errorf returns in handler paths with status.Errorf(codes.X, ...). Obvious mappings:

• Argument parsing/decoding (bech32, proof bytes, keys, hex/base64) → codes.InvalidArgument
• Explicit "not in DB" lookups → codes.NotFound
• Permission/macaroon → codes.PermissionDenied
• Shutdown / context canceled → codes.Canceled / codes.Unavailable
• Genuine internals (DB transaction failure, etc.) can keep the default Unknown/Internal

A stricter pattern is to introduce a small helper that wraps known sentinel errors into status codes at the RPC boundary, keeping handler internals free of grpc imports.

[kaldun-tech]

Hey I'd like to take a crack at this.

My plan would be to introduce a small helper at the RPC boundary that maps known sentinel errors to appropriate status codes (InvalidArgument for validation/decoding failures, NotFound for missing resources, etc.), keeping gRPC imports out of the internal handler logic.

I'll start with a focused first PR draft covering the cases called out in the issue (DecodeAddr, DecodeProof, ExportProof) to validate the pattern before going wider across the full RPC surface. LMK if there's a different preferred scope

[darioAnongba]

Hi and thanks for the proposal!

This ticket is one of the most significant we have to tackle in the next iteration and implies a somewhat big refactor of the RPC server because we are currently:

• "missing one layer": we do not differentiate between the "handler" and the business cases so there is no explicit RPC boundary. Business and handler logic are mixed in the rpcserver.go, which makes the error handling quite challenging without splitting these layers first.
• We do not consistently map to sentinel errors internally so the RPC layer has no knowledge of how to sanitize these to codes. It is a difficult task to dive into the codebase and find out what error type should be returned in each use case. The most common example is the "NotFound" one: at the data layer, a query not returning results is not an error, it is expected and valid behavior. Only the use case can recognize that an empty result is an error. Often, the use case is actually checking that nothing is found.

So missing this "business layer" prevents us from implementing this cleanly so I personally believe that we should add a "tech debt" task to split the rpcserver.go in 2 layers before we tackle this one.

That said, tackling the codes.InvalidArgument is feasible as that error is specific to the handlers and independent to the lower layers (it's purely based on the request).

cc: @jtobin, @GeorgeTsagk

[kaldun-tech]

Thanks Dario. I'll tackle the codes.InvalidArgument layer for the handlers in this first PR. Then we can plan out the system design for the big refactor of the RPC server you mention.

[darioAnongba]

Thanks Dario. I'll tackle the codes.InvalidArgument layer for the handlers in this first PR. Then we can plan out the system design for the big refactor of the RPC server you mention.

thanks!

[kaldun-tech]

Just sent PR #2112 for review. Planning to write up a doc with my findings on the RPC layer refactor design