rfq+rfqmsg: add structured price oracle error codes

.gitignore

@@ -24,6 +24,7 @@ cmd/tapd/tapd
 /itest/itest.test
 
 /docs/examples/basic-price-oracle/basic-price-oracle
+/docs/examples/basic-price-oracle/basic-price-oracle-example.log
 
 # Load test binaries and config
 /loadtest

docs/examples/basic-price-oracle/main.go

@@ -306,6 +306,7 @@ func (p *RpcPriceOracleServer) QueryAssetRates(_ context.Context,
 				Error: &oraclerpc.QueryAssetRatesErrResponse{
 					Message: "unsupported payment asset, " +
 						"only BTC is supported",
+					Code: 1,
 				},
 			},
 		}, nil
@@ -326,6 +327,7 @@ func (p *RpcPriceOracleServer) QueryAssetRates(_ context.Context,
 			Result: &oraclerpc.QueryAssetRatesResponse_Error{
 				Error: &oraclerpc.QueryAssetRatesErrResponse{
 					Message: "unsupported subject asset",
+					Code: 1,
 				},
 			},
 		}, nil

docs/release-notes/release-notes-0.7.0.md

@@ -26,8 +26,8 @@
 - [An integration test flake was
   fixed](https://github.com/lightninglabs/taproot-assets/pull/1651).
 
-- Fixed two send related bugs that would lead to either a `invalid transfer 
-  asset witness` or `unable to fund address send: error funding packet: unable 
+- Fixed two send related bugs that would lead to either a `invalid transfer
+  asset witness` or `unable to fund address send: error funding packet: unable
   to list eligible coins: unable to query commitments: mismatch of managed utxo
   and constructed tap commitment root` error when sending assets.
   The [PR that fixed the two
@@ -119,17 +119,25 @@
   when requesting quotes. The field can contain optional user or authentication
   information that helps the price oracle to decide on the optimal price rate to
   return.
+
+- The error code returned in a response from a price oracle now has a
+  [structured
+  form](https://github.com/lightninglabs/taproot-assets/pull/1766),
+  allowing price oracles to either indicate that a given asset is
+  unsupported, or simply to return an opaque error. "Unsupported asset"
+  errors are forwarded in reject messages sent to peers.
+
 - [Rename](https://github.com/lightninglabs/taproot-assets/pull/1682) the
   `MintAsset` RPC message field from `universe_commitments` to
   `enable_supply_commitments`.
-- The `SubscribeSendEvents` RPC now supports [historical event replay of 
+- The `SubscribeSendEvents` RPC now supports [historical event replay of
   completed sends with efficient database-level
   filtering](https://github.com/lightninglabs/taproot-assets/pull/1685).
 - [Add universe RPC endpoint FetchSupplyLeaves](https://github.com/lightninglabs/taproot-assets/pull/1693)
   that allows users to fetch the supply leaves of a universe supply commitment.
   This is useful for verification.
 
-- A [new field `unconfirmed_transfers` was added to the response of the 
+- A [new field `unconfirmed_transfers` was added to the response of the
   `ListBalances` RPC
   method](https://github.com/lightninglabs/taproot-assets/pull/1691) to indicate
   that unconfirmed asset-related transactions don't count toward the balance.
@@ -236,5 +244,6 @@
 
 - ffranr
 - George Tsagkarelis
+- jtobin
 - Olaoluwa Osuntokun
 - Oliver Gugger

rfq/negotiator.go

@@ -1,6 +1,7 @@
 package rfq
 
 import (
+	"errors"
 	"fmt"
 	"sync"
 	"time"
@@ -146,10 +147,9 @@
 	}
 
 	// Now we will check for an error in the response from the price oracle.
-	// If present, we will convert it to a string and return it as an error.
+	// If present, we will simply relay it.
 	if oracleResponse.Err != nil {
-		return nil, fmt.Errorf("failed to query price oracle for "+
-			"buy price: %s", oracleResponse.Err)
+		return nil, oracleResponse.Err
 	}
 
 	// By this point, the price oracle did not return an error or a buy
@@ -282,10 +282,9 @@
 	}
 
 	// Now we will check for an error in the response from the price oracle.
-	// If present, we will convert it to a string and return it as an error.
+	// If present, we will simply relay it.
 	if oracleResponse.Err != nil {
-		return nil, fmt.Errorf("failed to query price oracle for "+
-			"sell price: %s", oracleResponse.Err)
+		return nil, oracleResponse.Err
 	}
 
 	// By this point, the price oracle did not return an error or a sell
@@ -372,10 +371,12 @@
 			peerID, request.PriceOracleMetadata, IntentRecvPayment,
 		)
 		if err != nil {
-			// Send a reject message to the peer.
+			// Construct an appropriate RejectErr based on
+			// the oracle's response, and send it to the
+			// peer.
 			msg := rfqmsg.NewReject(
 				request.Peer, request.ID,
-				rfqmsg.ErrUnknownReject,
+				createCustomRejectErr(err),
 			)
 			sendOutgoingMsg(msg)
 
@@ -473,10 +474,12 @@
 			peerID, request.PriceOracleMetadata, IntentPayInvoice,
 		)
 		if err != nil {
-			// Send a reject message to the peer.
+			// Construct an appropriate RejectErr based on
+			// the oracle's response, and send it to the
+			// peer.
 			msg := rfqmsg.NewReject(
 				request.Peer, request.ID,
-				rfqmsg.ErrUnknownReject,
+				createCustomRejectErr(err),
 			)
 			sendOutgoingMsg(msg)
 
@@ -495,6 +498,36 @@
 	return nil
 }
 
+// createCustomRejectErr creates a RejectErr with code 0 and a custom message
+// based on an error response from a price oracle.
+func createCustomRejectErr(err error) rfqmsg.RejectErr {
+	var oracleError *OracleError
+
+	if errors.As(err, &oracleError) {
+		// The error is of the expected type, so switch on the error
+		// code returned by the oracle. If the code is benign, then the
+		// RejectErr will simply relay the oracle's message. Otherwise,
+		// we'll return an opaque rejection message.
+		switch oracleError.Code {
+
+		// The rejection message will state that the oracle doesn't
+		// support the asset.
+		case ErrUnsupportedOracleAsset:
+			msg := oracleError.Msg
+			return rfqmsg.ErrRejectWithCustomMsg(msg)
+
+		// The rejection message will be opaque, with the error
+		// unspecified.
+		default:
+			return rfqmsg.ErrUnknownReject
+		}
+	} else {
+		// The error is of an unexpected type, so just return an opaque
+		// error message.
+		return rfqmsg.ErrUnknownReject
+	}
+}
+
 // HandleOutgoingSellOrder handles an outgoing sell order by constructing sell
 // requests and passing them to the outgoing messages channel. These requests
 // are sent to peers.

rfq/oracle.go

@@ -86,12 +86,26 @@ const (
 // service.
 type OracleError struct {
 	// Code is a code which uniquely identifies the error type.
-	Code uint8
+	Code OracleErrorCode
 
 	// Msg is a human-readable error message.
 	Msg string
 }
 
+// OracleErrorCode uniquely identifies the kinds of error an oracle may
+// return.
+type OracleErrorCode uint8
+
+const (
+	// ErrUnspecifiedOracleError represents the case where the oracle has
+	// declined to give a more specific reason for the error.
+	ErrUnspecifiedOracleError OracleErrorCode = iota
+
+	// ErrUnsupportedOracleAsset represents the case in which an oracle does
+	// not provide quotes for the requested asset.
+	ErrUnsupportedOracleAsset
+)
+
 // Error returns a human-readable string representation of the error.
 func (o *OracleError) Error() string {
 	// Sanitise price oracle error message by truncating to 255 characters.
@@ -356,7 +370,8 @@ func (r *RpcPriceOracle) QuerySellPrice(ctx context.Context,
 
 		return &OracleResponse{
 			Err: &OracleError{
-				Msg: result.Error.Message,
+				Msg:  result.Error.Message,
+				Code: marshallErrorCode(result.Error.Code),
 			},
 		}, nil
 
@@ -365,6 +380,19 @@ func (r *RpcPriceOracle) QuerySellPrice(ctx context.Context,
 	}
 }
 
+// marshallErrorCode marshalls an over-the-wire error code into an
+// OracleErrorCode.
+func marshallErrorCode(code oraclerpc.ErrorCode) OracleErrorCode {
+	switch code {
+	case oraclerpc.ErrorCode_ERROR_UNSPECIFIED:
+		return ErrUnspecifiedOracleError
+	case oraclerpc.ErrorCode_ERROR_UNSUPPORTED:
+		return ErrUnsupportedOracleAsset
+	default:
+		return ErrUnspecifiedOracleError
+	}
+}
+
 // QueryBuyPrice returns a buy price for the given asset amount.
 func (r *RpcPriceOracle) QueryBuyPrice(ctx context.Context,
 	assetSpecifier asset.Specifier, assetMaxAmt fn.Option[uint64],
@@ -467,7 +495,8 @@ func (r *RpcPriceOracle) QueryBuyPrice(ctx context.Context,
 
 		return &OracleResponse{
 			Err: &OracleError{
-				Msg: result.Error.Message,
+				Msg:  result.Error.Message,
+				Code: marshallErrorCode(result.Error.Code),
 			},
 		}, nil
 

rfqmsg/reject.go

@@ -92,6 +92,15 @@ var (
 	}
 )
 
+// ErrRejectWithCustomMsg produces the "unknown" error code, but pairs
+// it with a custom error message.
+func ErrRejectWithCustomMsg(msg string) RejectErr {
+	return RejectErr{
+		Code: 0,
+		Msg:  msg,
+	}
+}
+
 const (
 	// latestRejectVersion is the latest supported reject wire message data
 	// field version.