oor: add OOR_REJECT_USER_BALANCE typed reject code + classifier

oor/errors.go

@@ -64,6 +64,35 @@ func (e *ErrOutputPolicyViolation) Is(target error) bool {
 	return ok
 }
 
+// ErrUserBalanceExceeded is the client-facing typed error returned when
+// the operator rejects an OOR submit because a recipient mailbox's
+// aggregate VTXO balance would exceed the operator's MaxUserBalance cap.
+//
+// Unlike ErrOutputPolicyViolation, this is NOT terminal for the same
+// output shape: the rejection clears once the recipient spends or
+// refreshes its balance down, so a custodial sender (e.g. a swap server
+// holding the value on the recipient's behalf) should retain the value
+// and retry later rather than restructuring the outputs. The wrapped
+// Reason carries the operator's human-readable explanation and is
+// suitable for surfacing directly in UX.
+type ErrUserBalanceExceeded struct {
+	Reason string
+}
+
+// Error returns a human-readable description of the rejection cause.
+func (e *ErrUserBalanceExceeded) Error() string {
+	return fmt.Sprintf("oor user balance exceeded: %s", e.Reason)
+}
+
+// Is reports whether target is also an *ErrUserBalanceExceeded,
+// supporting the standard errors.Is comparison without forcing callers
+// to compare reasons.
+func (e *ErrUserBalanceExceeded) Is(target error) bool {
+	_, ok := target.(*ErrUserBalanceExceeded)
+
+	return ok
+}
+
 // ErrInvalidAncestry is the typed error returned by the receive-side
 // ancestry cross-check when an operator-supplied IncomingVTXOMetadata
 // fails one of the structural invariants required to bind the produced
@@ -118,6 +147,11 @@ func ClassifySubmitError(err error) error {
 				Reason: rejected.Reason,
 			}
 
+		case oorpb.OORRejectCode_OOR_REJECT_USER_BALANCE:
+			return &ErrUserBalanceExceeded{
+				Reason: rejected.Reason,
+			}
+
 		case oorpb.OORRejectCode_OOR_REJECT_UNSPECIFIED:
 			// Unspecified rejection codes have no typed
 			// mapping; fall through to pass-through.

oor/errors_test.go

@@ -0,0 +1,85 @@
+package oor
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+
+	"github.com/lightninglabs/darepo-client/rpc/oorpb"
+	"github.com/stretchr/testify/require"
+)
+
+// TestClassifySubmitError verifies each typed operator rejection code maps to
+// its client-facing typed error, that the user-balance rejection is distinct
+// from the output-policy one (they have opposite retry semantics), and that
+// untyped errors pass through unchanged.
+func TestClassifySubmitError(t *testing.T) {
+	t.Parallel()
+
+	t.Run("user balance maps to typed error", func(t *testing.T) {
+		t.Parallel()
+
+		rejected := &oorpb.SubmitRejectedError{
+			Code:   oorpb.OORRejectCode_OOR_REJECT_USER_BALANCE,
+			Reason: "user balance exceeds maximum",
+		}
+
+		got := ClassifySubmitError(rejected)
+		require.ErrorIs(t, got, &ErrUserBalanceExceeded{})
+		require.Contains(t, got.Error(), "user balance exceeds maximum")
+	})
+
+	t.Run("user balance distinct from output policy", func(t *testing.T) {
+		t.Parallel()
+
+		balance := ClassifySubmitError(&oorpb.SubmitRejectedError{
+			Code: oorpb.OORRejectCode_OOR_REJECT_USER_BALANCE,
+		})
+		policy := ClassifySubmitError(&oorpb.SubmitRejectedError{
+			Code: oorpb.OORRejectCode_OOR_REJECT_OUTPUT_POLICY,
+		})
+
+		// A balance rejection must not be mistaken for a (terminal)
+		// output-policy rejection, since only the latter requires
+		// restructuring the outputs.
+		require.NotErrorIs(t, balance, &ErrOutputPolicyViolation{})
+		require.NotErrorIs(t, policy, &ErrUserBalanceExceeded{})
+	})
+
+	t.Run("output policy still maps", func(t *testing.T) {
+		t.Parallel()
+
+		got := ClassifySubmitError(&oorpb.SubmitRejectedError{
+			Code:   oorpb.OORRejectCode_OOR_REJECT_OUTPUT_POLICY,
+			Reason: "output 0 exceeds the per-VTXO maximum",
+		})
+		require.ErrorIs(t, got, &ErrOutputPolicyViolation{})
+	})
+
+	t.Run("wrapped rejection is unwrapped", func(t *testing.T) {
+		t.Parallel()
+
+		// errors.As must reach the typed rejection even when it is
+		// wrapped, so the daemon's outer context does not hide the
+		// code.
+		wrapped := fmt.Errorf("submit failed: %w",
+			&oorpb.SubmitRejectedError{
+				Code: oorpb.
+					OORRejectCode_OOR_REJECT_USER_BALANCE,
+			})
+
+		require.ErrorIs(
+			t, ClassifySubmitError(wrapped),
+			&ErrUserBalanceExceeded{},
+		)
+	})
+
+	t.Run("nil and untyped pass through", func(t *testing.T) {
+		t.Parallel()
+
+		require.NoError(t, ClassifySubmitError(nil))
+
+		plain := errors.New("connection reset")
+		require.Equal(t, plain, ClassifySubmitError(plain))
+	})
+}

rpc/oorpb/oorwire.proto

@@ -98,6 +98,14 @@ enum OORRejectCode {
     // must restructure the outputs (smaller amounts, more outputs)
     // before resubmitting.
     OOR_REJECT_OUTPUT_POLICY = 2;
+
+    // OOR_REJECT_USER_BALANCE indicates the submit would push a recipient
+    // mailbox's aggregate VTXO balance above the operator's advertised
+    // MaxUserBalance cap. Unlike OOR_REJECT_OUTPUT_POLICY, retrying the
+    // same shape can succeed once the recipient's balance drops (e.g. it
+    // spends or refreshes down), so a custodial sender may hold the value
+    // and retry later rather than restructuring the outputs.
+    OOR_REJECT_USER_BALANCE = 3;
 }
 
 // SubmitPackageRejection carries a typed rejection of an OOR submit.