docs: document transition matrix usage; add example (#25255)

Co-authored-by: Alex | Interchain Labs <alex@djinntek.world>

x/simulation/params.go

@@ -20,7 +20,20 @@ const (
 	maxTimePerBlock int64 = 10000
 )
 
-// TODO: explain transitional matrix usage
+// The transition matrices below control stochastic behavior in the simulation:
+//
+//   - defaultLivenessTransitionMatrix: models validator liveness across three
+//     states (online, spotty, offline). Each column represents the current state,
+//     each row represents the next state; entries are integer weights used for
+//     weighted random selection. Higher weights mean higher probability.
+//
+//   - defaultBlockSizeTransitionMatrix: models block size regimes across three
+//     states (large range, medium range, zero). Similar column-as-current,
+//     row-as-next convention applies.
+//
+// These matrices are fed into CreateTransitionMatrix, which precomputes column
+// totals for efficient sampling. During simulation, NextState(r, i) is called
+// with a deterministic RNG r and current state i to obtain the next state.
 var (
 	// Currently there are 3 different liveness types,
 	// fully online, spotty connection, offline.

x/simulation/transition_matrix.go

@@ -20,7 +20,25 @@ type TransitionMatrix struct {
 }
 
 // CreateTransitionMatrix creates a transition matrix from the provided weights.
-// TODO: Provide example usage
+//
+// Example:
+//
+//	weights := [][]int{
+//	  // From state 0 to states 0,1,2
+//	  {90, 10, 0},
+//	  // From state 1 to states 0,1,2
+//	  {20, 70, 10},
+//	  // From state 2 to states 0,1,2
+//	  {5,  15, 80},
+//	}
+//	tm, err := CreateTransitionMatrix(weights)
+//	if err != nil {
+//	  // handle error
+//	}
+//
+//	// NextState picks the next state from current state i.
+//	// r should be a deterministic *rand.Rand when used in simulations.
+//	// next := tm.NextState(r, i)
 func CreateTransitionMatrix(weights [][]int) (simulation.TransitionMatrix, error) {
 	n := len(weights)
 	for i := range n {