Merge pull request #151 from fystack/feat/nats-client-routing

Feat/nats client routing

Author: anhthii

README.md

@@ -166,6 +166,14 @@ $ mpcium start -n node2
 
 Mpcium supports flexible client authentication through a signer interface, allowing you to use either local keys or AWS KMS for signing operations.
 
+#### Client ID (Result Routing)
+
+When multiple client instances connect to the same MPC cluster, each client **must** set a unique `ClientID` to avoid result routing conflicts. Without distinct client IDs, two clients requesting operations concurrently may race for the same result message, causing one client to receive the other's response.
+
+- `ClientID` scopes the NATS consumer and result subject so each client only receives its own results.
+- Allowed characters: alphanumeric, hyphens, and underscores (e.g. `"backend-svc-1"`, `"mobile_api"`).
+- If you only run a single client instance, `ClientID` can be omitted (empty string).
+
 #### Local Signer (Ed25519)
 
 ```go
@@ -193,10 +201,11 @@ func main() {
         logger.Fatal("Failed to create local signer", err)
     }
 
-    // Create MPC client with signer
+    // Create MPC client with signer and a unique client ID
     mpcClient := client.NewMPCClient(client.Options{
         NatsConn: natsConn,
         Signer:   localSigner,
+        ClientID: "backend-svc-1", // unique per client instance
     })
 
     // Handle wallet creation results
@@ -253,6 +262,7 @@ func main() {
     mpcClient := client.NewMPCClient(client.Options{
         NatsConn: natsConn,
         Signer:   kmsSigner,
+        ClientID: "kms-client-1", // unique per client instance
     })
     // ... rest of the client code
 }

cmd/mpcium-cli/benchmark.go

@@ -80,6 +80,11 @@ func benchmarkCommand() *cli.Command {
 				Value:    false,
 				Category: "authentication",
 			},
+			&cli.StringFlag{
+				Name:     "client-id",
+				Usage:    "Client ID for result routing (scopes results to this client instance)",
+				Category: "configuration",
+			},
 			&cli.BoolFlag{
 				Name:     "debug",
 				Usage:    "Enable debug logging",
@@ -244,6 +249,7 @@ func createMPCClient(cmd *cli.Command) (client.MPCClient, error) {
 	opts := client.Options{
 		NatsConn: nc,
 		Signer:   signer,
+		ClientID: cmd.String("client-id"),
 	}
 	return client.NewMPCClient(opts), nil
 }

cmd/mpcium/main.go

@@ -216,17 +216,13 @@ func runNode(ctx context.Context, c *cli.Command) error {
 	}
 
 	directMessaging := messaging.NewNatsDirectMessaging(natsConn)
-	mqManager := messaging.NewNATsMessageQueueManager("mpc", []string{
-		"mpc.mpc_keygen_result.*",
-		event.SigningResultTopic,
-		"mpc.mpc_reshare_result.*",
-	}, natsConn)
+	mqManager := messaging.NewNATsMessageQueueManager("mpc", event.ResultStreamSubjects(), natsConn)
 
-	genKeyResultQueue := mqManager.NewMessageQueue("mpc_keygen_result")
+	genKeyResultQueue := mqManager.NewMessageQueue("mpc_keygen_result", event.KeygenResultSubscriptionSubject(""))
 	defer genKeyResultQueue.Close()
-	singingResultQueue := mqManager.NewMessageQueue("mpc_signing_result")
+	singingResultQueue := mqManager.NewMessageQueue("mpc_signing_result", event.SigningResultSubscriptionSubject(""))
 	defer singingResultQueue.Close()
-	reshareResultQueue := mqManager.NewMessageQueue("mpc_reshare_result")
+	reshareResultQueue := mqManager.NewMessageQueue("mpc_reshare_result", event.ReshareResultSubscriptionSubject(""))
 	defer reshareResultQueue.Close()
 
 	logger.Info("Starting mpcium node", "version", Version, "ID", nodeID, "name", nodeName)

e2e/base_test.go

@@ -196,6 +196,7 @@ func (s *E2ETestSuite) SetupMPCClient(t *testing.T) {
 	mpcClient := client.NewMPCClient(client.Options{
 		NatsConn: s.natsConn,
 		Signer:   localSigner,
+		ClientID: "e2e-suite",
 	})
 	s.mpcClient = mpcClient
 	t.Log("MPC client created")

e2e/go.mod

@@ -1,6 +1,6 @@
 module github.com/fystack/mpcium/e2e
 
-go 1.25.5
+go 1.25.8
 
 require (
 	github.com/bnb-chain/tss-lib/v2 v2.0.2