Integrator improvements for v1.1:

- Add Hooks struct for consensus event callbacks (OnPropose, OnVote,
  OnQCFormed, OnCommit, OnViewChange, OnTimeout)
- Add ConsensusState interface for read-only monitoring
- Add NewHotStuff2WithHooks constructor
- Add MessageCodec helper
- Standardise errors in classes:
  ErrConfig, ErrInvalidMessage, ErrByzantine, ErrInternal
- Update integration guide with observability and error handling docs

Author: edgedlt

config.go

@@ -72,42 +72,42 @@ func NewConfig[H Hash](opts ...ConfigOption[H]) (*Config[H], error) {
 // validate checks that all required configuration fields are set.
 func (c *Config[H]) validate() error {
 	if c.Validators == nil {
-		return fmt.Errorf("validators is required")
+		return wrapConfig("validators is required")
 	}
 
 	if c.PrivateKey == nil {
-		return fmt.Errorf("private key is required")
+		return wrapConfig("private key is required")
 	}
 
 	if c.Storage == nil {
-		return fmt.Errorf("storage is required")
+		return wrapConfig("storage is required")
 	}
 
 	if c.Network == nil {
-		return fmt.Errorf("network is required")
+		return wrapConfig("network is required")
 	}
 
 	if c.Executor == nil {
-		return fmt.Errorf("executor is required")
+		return wrapConfig("executor is required")
 	}
 
 	if c.Timer == nil {
-		return fmt.Errorf("timer is required")
+		return wrapConfig("timer is required")
 	}
 
 	if !c.Validators.Contains(c.MyIndex) {
-		return fmt.Errorf("my index %d is not in validator set", c.MyIndex)
+		return wrapConfigf("validator index %d not in validator set", c.MyIndex)
 	}
 
 	if c.CryptoScheme != CryptoSchemeEd25519 && c.CryptoScheme != CryptoSchemeBLS {
-		return fmt.Errorf("unsupported crypto scheme: %s", c.CryptoScheme)
+		return wrapConfigf("unsupported crypto scheme: %s", c.CryptoScheme)
 	}
 
 	// Validate Byzantine fault tolerance: n >= 3f + 1
 	n := c.Validators.Count()
 	f := c.Validators.F()
 	if n < 3*f+1 {
-		return fmt.Errorf("insufficient validators for Byzantine fault tolerance: n=%d, f=%d (need n >= 3f+1)", n, f)
+		return wrapConfigf("insufficient validators: n=%d, f=%d (need n >= 3f+1)", n, f)
 	}
 
 	return nil

config_test.go

@@ -1,6 +1,8 @@
 package hotstuff2
 
 import (
+	"errors"
+	"strings"
 	"testing"
 
 	"github.com/edgedlt/hotstuff2/internal/crypto"
@@ -110,8 +112,14 @@ func TestConfigValidationMissingFields(t *testing.T) {
 				t.Fatal("Expected error, got nil")
 			}
 
-			if err.Error() != "invalid config: "+tt.wantErr {
-				t.Errorf("Expected error '%s', got '%s'", tt.wantErr, err.Error())
+			// Check that it's a config error
+			if !errors.Is(err, ErrConfig) {
+				t.Errorf("Expected ErrConfig, got: %v", err)
+			}
+
+			// Check that error message contains the expected text
+			if !strings.Contains(err.Error(), tt.wantErr) {
+				t.Errorf("Expected error to contain '%s', got '%s'", tt.wantErr, err.Error())
 			}
 		})
 	}
@@ -135,8 +143,8 @@ func TestConfigInvalidIndex(t *testing.T) {
 		t.Fatal("Expected error for invalid index")
 	}
 
-	if err.Error() != "invalid config: my index 5 is not in validator set" {
-		t.Errorf("Unexpected error: %v", err)
+	if !errors.Is(err, ErrConfig) {
+		t.Errorf("Expected ErrConfig, got: %v", err)
 	}
 }
 

context.go

@@ -565,3 +565,54 @@ func (c *Context[H]) highQCView() uint32 {
 	}
 	return c.highQC.View()
 }
+
+// contextState wraps Context to implement ConsensusState interface.
+// This provides a read-only view of consensus state for external monitoring.
+type contextState[H Hash] struct {
+	ctx *Context[H]
+}
+
+// View returns the current view number.
+func (s *contextState[H]) View() uint32 {
+	return s.ctx.View()
+}
+
+// Height returns the height of the last committed block.
+func (s *contextState[H]) Height() uint32 {
+	s.ctx.mu.RLock()
+	defer s.ctx.mu.RUnlock()
+
+	maxHeight := uint32(0)
+	for height := range s.ctx.committed {
+		if height > maxHeight {
+			maxHeight = height
+		}
+	}
+	return maxHeight
+}
+
+// LockedQCView returns the view of the locked QC, or 0 if none.
+func (s *contextState[H]) LockedQCView() uint32 {
+	s.ctx.mu.RLock()
+	defer s.ctx.mu.RUnlock()
+	return s.ctx.lockedQCView()
+}
+
+// HighQCView returns the view of the highest QC seen, or 0 if none.
+func (s *contextState[H]) HighQCView() uint32 {
+	s.ctx.mu.RLock()
+	defer s.ctx.mu.RUnlock()
+	return s.ctx.highQCView()
+}
+
+// CommittedCount returns the number of committed blocks.
+func (s *contextState[H]) CommittedCount() int {
+	s.ctx.mu.RLock()
+	defer s.ctx.mu.RUnlock()
+	return len(s.ctx.committed)
+}
+
+// State returns a read-only ConsensusState for the context.
+func (c *Context[H]) State() ConsensusState {
+	return &contextState[H]{ctx: c}
+}