fix: support legacy format (#5498)

Author: sbackend123

pkg/bzz/underlay.go

@@ -39,12 +39,27 @@ const maxUnderlaysPerPeer = 20
 const maxUnderlayBytes = 2048
 
 // SerializeUnderlays serializes a slice of multiaddrs into a single byte slice.
+// If the slice contains exactly one address, the standard, backward-compatible
+// multiaddr format is used. For zero or more than one address, a custom list format
+// prefixed with a magic byte is utilized.
+// Returns an error wrapping ErrUnderlayCountExceeded or ErrUnderlayByteSizeExceeded
+// if the limits are violated.
 func SerializeUnderlays(addrs []multiaddr.Multiaddr) ([]byte, error) {
 	if len(addrs) > maxUnderlaysPerPeer {
 		return nil, fmt.Errorf("underlay count %d exceeds maximum of %d: %w", len(addrs), maxUnderlaysPerPeer, ErrUnderlayCountExceeded)
 	}
 
-	// The format is: [prefix_byte][varint_len_1][addr_1_bytes][varint_len_2][addr_2_bytes]...
+	// Backward compatibility if exactly one address is present.
+	if len(addrs) == 1 {
+		b := addrs[0].Bytes()
+		if len(b) > maxUnderlayBytes {
+			return nil, fmt.Errorf("underlay data size %d exceeds maximum of %d bytes: %w", len(b), maxUnderlayBytes, ErrUnderlayByteSizeExceeded)
+		}
+		return b, nil
+	}
+
+	// For 0 or 2+ addresses, the custom list format with the prefix is used.
+	// The format is: [prefix_byte][varint_len_1][addr_1_bytes]...
 	var buf bytes.Buffer
 	buf.WriteByte(underlayListPrefix)
 
@@ -62,6 +77,8 @@ func SerializeUnderlays(addrs []multiaddr.Multiaddr) ([]byte, error) {
 }
 
 // DeserializeUnderlays deserializes a byte slice into a slice of multiaddrs.
+// The data format is automatically detected as either a single legacy multiaddr
+// or a list of multiaddrs (identified by underlayListPrefix), and is parsed accordingly.
 func DeserializeUnderlays(data []byte) ([]multiaddr.Multiaddr, error) {
 	if len(data) == 0 {
 		return nil, errors.New("cannot deserialize empty byte slice")
@@ -71,14 +88,22 @@ func DeserializeUnderlays(data []byte) ([]multiaddr.Multiaddr, error) {
 		return nil, fmt.Errorf("underlay data size %d exceeds maximum of %d bytes: %w", len(data), maxUnderlayBytes, ErrUnderlayByteSizeExceeded)
 	}
 
-	if data[0] != underlayListPrefix {
-		return nil, errors.New("invalid underlay payload: missing list prefix")
+	// If the data begins with the magic prefix, it is handled as a list.
+	if data[0] == underlayListPrefix {
+		return deserializeList(data[1:])
 	}
 
-	return deserializeList(data[1:])
+	// Otherwise, the data is handled as a single, backward-compatible multiaddr.
+	addr, err := multiaddr.NewMultiaddrBytes(data)
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse as single multiaddr: %w", err)
+	}
+	// The result is returned as a single-element slice for a consistent return type.
+	return []multiaddr.Multiaddr{addr}, nil
 }
 
-// deserializeList handles the parsing of the underlays list format.
+// deserializeList handles the parsing of the custom list format.
+// The provided data is expected to have already been stripped of the underlayListPrefix.
 func deserializeList(data []byte) ([]multiaddr.Multiaddr, error) {
 	var addrs []multiaddr.Multiaddr
 	r := bytes.NewReader(data)

pkg/bzz/underlay_test.go

@@ -29,6 +29,19 @@ func TestSerializeUnderlays(t *testing.T) {
 		}
 	})
 
+	t.Run("single address list", func(t *testing.T) {
+		addrs := []multiaddr.Multiaddr{dnsSwarmAddr}
+		serialized := mustSerializeUnderlays(t, addrs)
+		expected := dnsSwarmAddr.Bytes() // Should be legacy format without prefix
+
+		if !bytes.Equal(serialized, expected) {
+			t.Errorf("expected single address to serialize to legacy format %x, got %x", expected, serialized)
+		}
+		if serialized[0] == bzz.UnderlayListPrefix {
+			t.Error("single address serialization should not have the list prefix")
+		}
+	})
+
 	t.Run("empty list", func(t *testing.T) {
 		addrs := []multiaddr.Multiaddr{}
 		serialized := mustSerializeUnderlays(t, addrs)
@@ -77,6 +90,17 @@ func TestDeserializeUnderlays(t *testing.T) {
 		}
 	})
 
+	t.Run("single legacy multiaddr", func(t *testing.T) {
+		singleBytes := wssAddr.Bytes()
+		deserialized, err := bzz.DeserializeUnderlays(singleBytes)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(deserialized) != 1 || !deserialized[0].Equal(wssAddr) {
+			t.Errorf("expected [%v], got %v", wssAddr, deserialized)
+		}
+	})
+
 	t.Run("empty byte slice", func(t *testing.T) {
 		_, err := bzz.DeserializeUnderlays([]byte{})
 		if err == nil {