YNU-915: return success on absent-resource GET endpoints

cerebro/commands.go

@@ -636,6 +636,10 @@ func (o *Operator) getHomeChannel(ctx context.Context, wallet, asset string) {
 		fmt.Printf("ERROR: Failed to get home channel: %v\n", err)
 		return
 	}
+	if channel == nil {
+		fmt.Printf("No home channel found for %s (%s)\n", wallet, asset)
+		return
+	}
 
 	typeStr := "unknown"
 	switch channel.Type {
@@ -675,6 +679,10 @@ func (o *Operator) getEscrowChannel(ctx context.Context, escrowChannelID string)
 		fmt.Printf("ERROR: Failed to get escrow channel: %v\n", err)
 		return
 	}
+	if channel == nil {
+		fmt.Printf("No escrow channel found with ID %s\n", escrowChannelID)
+		return
+	}
 
 	typeStr := "unknown"
 	switch channel.Type {
@@ -834,6 +842,10 @@ func (o *Operator) getLatestState(ctx context.Context, wallet, asset string) {
 		fmt.Printf("ERROR: Failed to get state: %v\n", err)
 		return
 	}
+	if state == nil {
+		fmt.Printf("No state found for %s (%s)\n", wallet, asset)
+		return
+	}
 
 	fmt.Printf("Latest State for %s (%s)\n", wallet, asset)
 	fmt.Println("====================================")

docs/api.yaml

@@ -525,7 +525,7 @@ api:
         - version: v1
           methods:
             - name: get_home_channel
-              description: Retrieve current on-chain home channel information
+              description: Retrieve current on-chain home channel information. Returns a successful response with `channel` omitted when no home channel exists for the wallet/asset pair.
               request:
                 - field_name: wallet
                   type: string
@@ -536,13 +536,12 @@ api:
               response:
                 - field_name: channel
                   type: channel
-                  description: The on-chain channel information
-              errors:
-                - message: channel_not_found
-                  description: The specified channel was not found
+                  description: The on-chain channel information; omitted when no home channel exists for the wallet/asset pair
+                  optional: true
+              errors: []
             - name: get_escrow_channel
               description: |
-                Retrieve current on-chain escrow channel information.
+                Retrieve current on-chain escrow channel information. Returns a successful response with `channel` omitted when no escrow channel exists for the given ID.
 
                 Note: when the escrow channel has been closed by the on-chain
                 purge queue (no signed FINALIZE_ESCROW_DEPOSIT was received
@@ -556,10 +555,9 @@ api:
               response:
                 - field_name: channel
                   type: channel
-                  description: The on-chain channel information
-              errors:
-                - message: channel_not_found
-                  description: The specified channel was not found
+                  description: The on-chain channel information; omitted when no escrow channel exists for the given ID
+                  optional: true
+              errors: []
             - name: get_channels
               description: Retrieve all channels for a user with optional filtering
               request:
@@ -592,7 +590,7 @@ api:
                 - message: invalid_parameters
                   description: The request parameters are invalid
             - name: get_latest_state
-              description: Retrieve the current state of the user stored on the Node
+              description: Retrieve the current state of the user stored on the Node. Returns a successful response with `state` omitted when no state is stored for the wallet/asset pair.
               request:
                 - field_name: wallet
                   type: string
@@ -607,10 +605,9 @@ api:
               response:
                 - field_name: state
                   type: state
-                  description: The current state of the user
-              errors:
-                - message: channel_not_found
-                  description: The specified channel was not found
+                  description: The current state of the user; omitted when no state is stored for the wallet/asset pair
+                  optional: true
+              errors: []
             - name: request_creation
               description: Request the creation of a channel from Node
               request:
@@ -766,18 +763,17 @@ api:
 
               errors: []
             - name: get_app_definition
-              description: Retrieve the application definition for a specific app session
+              description: Retrieve the application definition for a specific app session. Returns a successful response with `definition` omitted when no app session exists for the given ID.
               request:
                 - field_name: app_session_id
                   type: string
                   description: The application session ID
               response:
                 - field_name: definition
                   type: app_definition
-                  description: The application definition
-              errors:
-                - message: app_session_not_found
-                  description: The specified app session was not found
+                  description: The application definition; omitted when no app session exists for the given ID
+                  optional: true
+              errors: []
             - name: get_app_sessions
               description: List all application sessions for a participant with optional filtering
               request:

nitronode/api/app_session_v1/get_app_definition.go

@@ -14,7 +14,7 @@ func (h *Handler) GetAppDefinition(c *rpc.Context) {
 		return
 	}
 
-	var definition rpc.AppDefinitionV1
+	var definition *rpc.AppDefinitionV1
 
 	err := h.useStoreInTx(func(store Store) error {
 		session, err := store.GetAppSession(req.AppSessionID)
@@ -23,7 +23,7 @@ func (h *Handler) GetAppDefinition(c *rpc.Context) {
 		}
 
 		if session == nil {
-			return rpc.Errorf("app_session_not_found")
+			return nil
 		}
 
 		// Convert participants
@@ -35,7 +35,7 @@ func (h *Handler) GetAppDefinition(c *rpc.Context) {
 			}
 		}
 
-		definition = rpc.AppDefinitionV1{
+		definition = &rpc.AppDefinitionV1{
 			Application:  session.ApplicationID,
 			Participants: participants,
 			Quorum:       session.Quorum,

nitronode/api/app_session_v1/get_app_definition_test.go

@@ -84,6 +84,7 @@ func TestGetAppDefinition_Success(t *testing.T) {
 	var response rpc.AppSessionsV1GetAppDefinitionResponse
 	err = ctx.Response.Payload.Translate(&response)
 	require.NoError(t, err)
+	require.NotNil(t, response.Definition)
 
 	assert.Equal(t, "game", response.Definition.Application)
 	assert.Len(t, response.Definition.Participants, 2)
@@ -143,9 +144,14 @@ func TestGetAppDefinition_NotFound(t *testing.T) {
 	// Execute
 	handler.GetAppDefinition(ctx)
 
-	// Assert
-	assert.NotNil(t, ctx.Response.Error())
-	assert.Contains(t, ctx.Response.Error().Error(), "app_session_not_found")
+	// Assert: absence is a successful response with definition == nil
+	assert.NotNil(t, ctx.Response.Payload)
+	assert.Nil(t, ctx.Response.Error())
+
+	var response rpc.AppSessionsV1GetAppDefinitionResponse
+	err = ctx.Response.Payload.Translate(&response)
+	require.NoError(t, err)
+	assert.Nil(t, response.Definition)
 
 	// Verify all mock expectations
 	mockStore.AssertExpectations(t)

nitronode/api/channel_v1/get_escrow_channel.go

@@ -25,11 +25,6 @@ func (h *Handler) GetEscrowChannel(c *rpc.Context) {
 		if err != nil {
 			return rpc.Errorf("failed to get channel: %v", err)
 		}
-
-		if channel == nil {
-			return rpc.Errorf("channel_not_found")
-		}
-
 		return nil
 	})
 
@@ -38,8 +33,10 @@ func (h *Handler) GetEscrowChannel(c *rpc.Context) {
 		return
 	}
 
-	response := rpc.ChannelsV1GetEscrowChannelResponse{
-		Channel: coreChannelToRPC(*channel),
+	response := rpc.ChannelsV1GetEscrowChannelResponse{}
+	if channel != nil {
+		rpcChannel := coreChannelToRPC(*channel)
+		response.Channel = &rpcChannel
 	}
 
 	payload, err := rpc.NewPayload(response)

nitronode/api/channel_v1/get_escrow_channel_test.go

@@ -87,6 +87,7 @@ func TestGetEscrowChannel_Success(t *testing.T) {
 	var response rpc.ChannelsV1GetEscrowChannelResponse
 	err = ctx.Response.Payload.Translate(&response)
 	require.NoError(t, err)
+	require.NotNil(t, response.Channel)
 
 	assert.Equal(t, escrowChannelID, response.Channel.ChannelID)
 	assert.Equal(t, userWallet, response.Channel.UserWallet)
@@ -97,3 +98,50 @@ func TestGetEscrowChannel_Success(t *testing.T) {
 	// Verify all mock expectations
 	mockTxStore.AssertExpectations(t)
 }
+
+func TestGetEscrowChannel_NotFound(t *testing.T) {
+	mockTxStore := new(MockStore)
+	mockAssetStore := new(MockAssetStore)
+	mockSigner := NewMockSigner()
+	nodeSigner, _ := core.NewChannelDefaultSigner(mockSigner)
+	mockStatePacker := new(MockStatePacker)
+
+	handler := &Handler{
+		stateAdvancer: core.NewStateAdvancerV1(mockAssetStore),
+		statePacker:   mockStatePacker,
+		useStoreInTx: func(h StoreTxHandler) error {
+			return h(mockTxStore)
+		},
+		nodeSigner:       nodeSigner,
+		nodeAddress:      mockSigner.PublicKey().Address().String(),
+		minChallenge:     3600,
+		metrics:          metrics.NewNoopRuntimeMetricExporter(),
+		maxSessionKeyIDs: 256,
+		actionGateway:    &MockActionGateway{},
+	}
+
+	escrowChannelID := "0xMissingEscrowChannel"
+	mockTxStore.On("GetChannelByID", escrowChannelID).Return(nil, nil)
+
+	reqPayload := rpc.ChannelsV1GetEscrowChannelRequest{EscrowChannelID: escrowChannelID}
+	payload, err := rpc.NewPayload(reqPayload)
+	require.NoError(t, err)
+
+	ctx := &rpc.Context{
+		Context: context.Background(),
+		Request: rpc.Message{Method: "channels.v1.get_escrow_channel", Payload: payload},
+	}
+
+	handler.GetEscrowChannel(ctx)
+
+	// Absence is a successful response with channel == nil.
+	assert.NotNil(t, ctx.Response.Payload)
+	assert.Nil(t, ctx.Response.Error())
+
+	var response rpc.ChannelsV1GetEscrowChannelResponse
+	err = ctx.Response.Payload.Translate(&response)
+	require.NoError(t, err)
+	assert.Nil(t, response.Channel)
+
+	mockTxStore.AssertExpectations(t)
+}

nitronode/api/channel_v1/get_home_channel.go

@@ -27,11 +27,6 @@ func (h *Handler) GetHomeChannel(c *rpc.Context) {
 		if err != nil {
 			return rpc.Errorf("failed to get home channel: %v", err)
 		}
-
-		if channel == nil {
-			return rpc.Errorf("channel_not_found")
-		}
-
 		return nil
 	})
 
@@ -40,8 +35,10 @@ func (h *Handler) GetHomeChannel(c *rpc.Context) {
 		return
 	}
 
-	response := rpc.ChannelsV1GetHomeChannelResponse{
-		Channel: coreChannelToRPC(*channel),
+	response := rpc.ChannelsV1GetHomeChannelResponse{}
+	if channel != nil {
+		rpcChannel := coreChannelToRPC(*channel)
+		response.Channel = &rpcChannel
 	}
 
 	payload, err := rpc.NewPayload(response)

nitronode/api/channel_v1/get_home_channel_test.go

@@ -89,6 +89,7 @@ func TestGetHomeChannel_Success(t *testing.T) {
 	var response rpc.ChannelsV1GetHomeChannelResponse
 	err = ctx.Response.Payload.Translate(&response)
 	require.NoError(t, err)
+	require.NotNil(t, response.Channel)
 
 	assert.Equal(t, homeChannelID, response.Channel.ChannelID)
 	assert.Equal(t, userWallet, response.Channel.UserWallet)
@@ -156,9 +157,14 @@ func TestGetHomeChannel_NotFound(t *testing.T) {
 	// Execute
 	handler.GetHomeChannel(ctx)
 
-	// Assert
-	assert.NotNil(t, ctx.Response.Error())
-	assert.Contains(t, ctx.Response.Error().Error(), "channel_not_found")
+	// Assert: absence is a successful response with channel == nil
+	assert.NotNil(t, ctx.Response.Payload)
+	assert.Nil(t, ctx.Response.Error())
+
+	var response rpc.ChannelsV1GetHomeChannelResponse
+	err = ctx.Response.Payload.Translate(&response)
+	require.NoError(t, err)
+	assert.Nil(t, response.Channel)
 
 	// Verify all mock expectations
 	mockTxStore.AssertExpectations(t)

nitronode/api/channel_v1/get_latest_state.go

@@ -20,18 +20,14 @@ func (h *Handler) GetLatestState(c *rpc.Context) {
 	}
 	req.Wallet = normalizedWallet
 
-	var state core.State
+	var state *core.State
 	err = h.useStoreInTx(func(tx Store) error {
 		lastState, err := tx.GetLastUserState(req.Wallet, req.Asset, req.OnlySigned)
 		if err != nil {
 			return rpc.Errorf("failed to get last user state: %v", err)
 		}
 
-		if lastState == nil {
-			return rpc.Errorf("channel not found")
-		}
-
-		state = *lastState
+		state = lastState
 		return nil
 	})
 
@@ -40,8 +36,10 @@ func (h *Handler) GetLatestState(c *rpc.Context) {
 		return
 	}
 
-	response := rpc.ChannelsV1GetLatestStateResponse{
-		State: coreStateToRPC(state),
+	response := rpc.ChannelsV1GetLatestStateResponse{}
+	if state != nil {
+		rpcState := coreStateToRPC(*state)
+		response.State = &rpcState
 	}
 
 	payload, err := rpc.NewPayload(response)

nitronode/api/channel_v1/get_latest_state_test.go

@@ -99,6 +99,7 @@ func TestGetLatestState_Success(t *testing.T) {
 	var response rpc.ChannelsV1GetLatestStateResponse
 	err = ctx.Response.Payload.Translate(&response)
 	require.NoError(t, err)
+	require.NotNil(t, response.State)
 
 	assert.Equal(t, state.ID, response.State.ID)
 	assert.Equal(t, userWallet, response.State.UserWallet)
@@ -198,6 +199,7 @@ func TestGetLatestState_OnlySigned(t *testing.T) {
 	var response rpc.ChannelsV1GetLatestStateResponse
 	err = ctx.Response.Payload.Translate(&response)
 	require.NoError(t, err)
+	require.NotNil(t, response.State)
 
 	assert.Equal(t, state.ID, response.State.ID)
 	assert.Equal(t, "3", response.State.Version)
@@ -236,3 +238,39 @@ func TestGetLatestState_NormalizesWallet(t *testing.T) {
 	require.Nil(t, ctx.Response.Error())
 	mockTxStore.AssertExpectations(t)
 }
+
+// TestGetLatestState_NotFound verifies absent state returns a successful response with nil state payload.
+func TestGetLatestState_NotFound(t *testing.T) {
+	mockTxStore := new(MockStore)
+
+	handler := &Handler{
+		useStoreInTx: func(h StoreTxHandler) error { return h(mockTxStore) },
+		metrics:      metrics.NewNoopRuntimeMetricExporter(),
+	}
+
+	userWallet := "0x1234567890123456789012345678901234567890"
+	asset := "USDC"
+	mockTxStore.On("GetLastUserState", userWallet, asset, false).Return(nil, nil)
+
+	reqPayload := rpc.ChannelsV1GetLatestStateRequest{Wallet: userWallet, Asset: asset}
+	payload, err := rpc.NewPayload(reqPayload)
+	require.NoError(t, err)
+
+	ctx := &rpc.Context{
+		Context: context.Background(),
+		Request: rpc.Message{Method: "channels.v1.get_latest_state", Payload: payload},
+	}
+
+	handler.GetLatestState(ctx)
+
+	// Absence is a successful response with state == nil.
+	require.NotNil(t, ctx.Response.Payload)
+	require.NoError(t, ctx.Response.Error())
+
+	var response rpc.ChannelsV1GetLatestStateResponse
+	err = ctx.Response.Payload.Translate(&response)
+	require.NoError(t, err)
+	assert.Nil(t, response.State)
+
+	mockTxStore.AssertExpectations(t)
+}