fix(protocol): localtxsubmission idle / done (#1876)

Signed-off-by: Chris Gianelloni <wolf31o2@blinklabs.io>

Author: wolf31o2

protocol/localtxsubmission/README.md

@@ -15,11 +15,14 @@ The LocalTxSubmission protocol submits transactions to the local node's mempool.
 ```
 ┌──────┐    SubmitTx     ┌──────┐
 │ Idle │ ───────────────►│ Busy │
-└──────┘                 └──┬───┘
-   ▲                        │
-   │                        │ AcceptTx
-   │                        │ RejectTx
-   │                        │
+└──┬───┘                 └──┬───┘
+   ▲  │                     │
+   │  │ Done                │ AcceptTx
+   │  │                     │ RejectTx
+   │  ▼                     │
+   │ ┌──────┐               │
+   │ │ Done │               │
+   │ └──────┘               │
    └────────────────────────┘
 ```
 
@@ -38,13 +41,15 @@ The LocalTxSubmission protocol submits transactions to the local node's mempool.
 | `SubmitTx` | 0 | Client → Server | Submit a transaction |
 | `AcceptTx` | 1 | Server → Client | Transaction accepted |
 | `RejectTx` | 2 | Server → Client | Transaction rejected |
+| `Done` | 3 | Client → Server | Terminate protocol |
 
 ## State Transitions
 
 ### From Idle (Client Agency)
 | Message | New State |
 |---------|-----------|
 | `SubmitTx` | Busy |
+| `Done` | Done |
 
 ### From Busy (Server Agency)
 | Message | New State |

protocol/localtxsubmission/client_test.go

@@ -125,6 +125,44 @@ func TestSubmitTxAccept(t *testing.T) {
 	)
 }
 
+// TestSubmitTxAcceptThenDone reproduces the cardano-cli submit flow from dingo
+// issue #2788: submit a transaction, receive AcceptTx, then cleanly close the
+// protocol by sending MsgDone from the Idle state. Before the Idle->Done
+// transition existed, Stop() produced a protocol-state error that tore down the
+// node-to-client connection.
+func TestSubmitTxAcceptThenDone(t *testing.T) {
+	testTx := test.DecodeHexString("abcdef0123456789")
+	conversation := append(
+		conversationHandshakeSubmitTx,
+		ouroboros_mock.ConversationEntryOutput{
+			ProtocolId: localtxsubmission.ProtocolId,
+			IsResponse: true,
+			Messages: []protocol.Message{
+				localtxsubmission.NewMsgAcceptTx(),
+			},
+		},
+		ouroboros_mock.ConversationEntryInput{
+			ProtocolId:  localtxsubmission.ProtocolId,
+			MessageType: localtxsubmission.MessageTypeDone,
+		},
+	)
+	runTest(
+		t,
+		conversation,
+		func(t *testing.T, oConn *ouroboros.Connection) {
+			if err := oConn.LocalTxSubmission().Client.SubmitTx(
+				ledger.TxTypeBabbage,
+				testTx,
+			); err != nil {
+				t.Fatalf("received unexpected error on SubmitTx: %s", err)
+			}
+			if err := oConn.LocalTxSubmission().Client.Stop(); err != nil {
+				t.Fatalf("received unexpected error on Stop: %s", err)
+			}
+		},
+	)
+}
+
 func TestSubmitTxRject(t *testing.T) {
 	testTx := test.DecodeHexString("abcdef0123456789")
 	expectedErr := localtxsubmission.TransactionRejectedError{

protocol/localtxsubmission/localtxsubmission.go

@@ -43,6 +43,14 @@ var StateMap = protocol.StateMap{
 				MsgType:  MessageTypeSubmitTx,
 				NewState: stateBusy,
 			},
+			{
+				// The client may terminate the protocol from Idle. cardano-cli
+				// sends MsgDone to cleanly close after a submit; without this
+				// transition the connection is torn down with a protocol error
+				// (dingo issue #2788).
+				MsgType:  MessageTypeDone,
+				NewState: stateDone,
+			},
 		},
 	},
 	stateBusy: protocol.StateMapEntry{

protocol/localtxsubmission/statemap_test.go

@@ -0,0 +1,48 @@
+// Copyright 2026 Blink Labs Software
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package localtxsubmission
+
+import "testing"
+
+// The LocalTxSubmission client has agency in the Idle state and may terminate
+// the protocol by sending MsgDone (per the mini-protocol spec). Without an
+// Idle->Done transition, gouroboros rejects cardano-cli's clean shutdown with
+// "message *localtxsubmission.MsgDone not allowed in current protocol state
+// Idle" and tears down the whole node-to-client connection (dingo issue #2788).
+func TestStateMapIdleAllowsDone(t *testing.T) {
+	entry, ok := StateMap[stateIdle]
+	if !ok {
+		t.Fatal("StateMap has no entry for the Idle state")
+	}
+	found := false
+	for _, transition := range entry.Transitions {
+		if transition.MsgType != MessageTypeDone {
+			continue
+		}
+		found = true
+		if transition.NewState != stateDone {
+			t.Fatalf(
+				"Idle MsgDone transitions to %s, want Done",
+				transition.NewState,
+			)
+		}
+	}
+	if !found {
+		t.Fatal(
+			"Idle state does not allow MsgDone; cardano-cli cannot cleanly " +
+				"close the protocol (issue #2788)",
+		)
+	}
+}