feat: Reputation: CNS-1004 - QoS excellence epoch score aggregation

proto/lavanet/lava/pairing/params.proto

@@ -23,6 +23,6 @@ message Params {
     (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
     (gogoproto.nullable)   = false
   ];
-  int64 reputation_half_life_factor = 17 [(gogoproto.moretags) = "yaml:\"reputation_half_life_factor\""];
+  uint64 reputation_half_life_factor = 17 [(gogoproto.moretags) = "yaml:\"reputation_half_life_factor\""];
   uint64 reputation_relay_failure_cost = 18 [(gogoproto.moretags) = "yaml:\"reputation_relay_failure_cost\""];
 }

proto/lavanet/lava/pairing/query.proto

@@ -5,6 +5,7 @@ import "gogoproto/gogo.proto";
 import "google/api/annotations.proto";
 import "cosmos/base/query/v1beta1/pagination.proto";
 import "lavanet/lava/pairing/params.proto";
+import "lavanet/lava/pairing/reputation.proto";
 import "lavanet/lava/spec/spec.proto";
 
 
@@ -80,9 +81,19 @@ service Query {
 	}
 
 // Queries a for the aggregated CU of all ProviderEpochCu objects all the providers.
-rpc ProvidersEpochCu(QueryProvidersEpochCuRequest) returns (QueryProvidersEpochCuResponse) {
-	option (google.api.http).get = "/lavanet/lava/pairing/providers_epoch_cu";
-}
+	rpc ProvidersEpochCu(QueryProvidersEpochCuRequest) returns (QueryProvidersEpochCuResponse) {
+		option (google.api.http).get = "/lavanet/lava/pairing/providers_epoch_cu";
+	}
+
+// Queries a for a provider reputation.
+	rpc ProviderReputation(QueryProviderReputationRequest) returns (QueryProviderReputationResponse) {
+		option (google.api.http).get = "/lavanet/lava/pairing/provider_reputation/{provider}/{chainID}/{cluster}";
+	}
+
+// Queries a for a provider reputation's details (mainly for developers).
+	rpc ProviderReputationDetails(QueryProviderReputationDetailsRequest) returns (QueryProviderReputationDetailsResponse) {
+		option (google.api.http).get = "/lavanet/lava/pairing/provider_reputation_details/{address}/{chainID}/{cluster}";
+	}
 
 	// this line is used by starport scaffolding # 2
 
@@ -238,4 +249,39 @@ message QueryProvidersEpochCuResponse {
 message ProviderCuInfo {
 	string provider = 1;
 	uint64 cu = 2;
+}
+
+message QueryProviderReputationRequest {
+	string provider = 1;
+	string chainID = 2;
+	string cluster = 3;
+}
+
+message ReputationData {
+	uint64 rank = 1; // rank compared to other providers
+	uint64 providers = 2; // amount of providers with the same chainID+cluster
+	string overall_performance = 3; // overall performance metric which can be "good", "bad", or "low variance"
+	string chainID = 4;
+	string cluster = 5;
+}
+
+message QueryProviderReputationResponse {
+	repeated ReputationData data = 1 [(gogoproto.nullable) = false];
+}
+
+message QueryProviderReputationDetailsRequest {
+	string address = 1;
+	string chainID = 2;
+	string cluster = 3;
+}
+
+message ReputationDevData {
+	Reputation reputation = 1 [(gogoproto.nullable) = false];
+	ReputationPairingScore reputation_pairing_score = 2 [(gogoproto.nullable) = false];
+	string chainID = 4;
+	string cluster = 5;
+}
+
+message QueryProviderReputationDetailsResponse {
+	repeated ReputationDevData data = 1 [(gogoproto.nullable) = false];
 }

proto/lavanet/lava/pairing/relay.proto

@@ -95,16 +95,23 @@ message RelayReply {
 }
 
 message QualityOfServiceReport{
+    // Latency of provider answers in milliseconds, range 0-inf, lower is better
     string latency = 1 [
         (gogoproto.moretags) = "yaml:\"Latency\"",
         (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
         (gogoproto.nullable)   = false
         ];
+
+    // Percentage of times the provider returned a non-error response, range 0-1, higher is better
     string availability  = 2 [
         (gogoproto.moretags) = "yaml:\"availability\"",
         (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
         (gogoproto.nullable)   = false
         ];
+
+    // Amount of time the provider is not synced (have the latest block) in milliseconds, range 0-inf, lower is better.
+    // Example: in ETH we have 15sec block time. So sync = 15000 means that the provider is one block
+    // behind the actual latest block.
     string sync = 3 [
         (gogoproto.moretags) = "yaml:\"sync\"",
         (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",

scripts/test/cli_test.sh

@@ -157,6 +157,8 @@ trace lavad q pairing static-providers-list LAV1 >/dev/null
 trace lavad q pairing user-entry $(lavad keys show alice -a) ETH1 20 >/dev/null
 trace lavad q pairing verify-pairing STRK $(lavad keys show alice -a) $(lavad keys show alice -a) 60 >/dev/null
 trace lavad q pairing provider-pairing-chance $(lavad keys show servicer1 -a) STRK 1 "" >/dev/null
+trace lavad q pairing provider-reputation $(lavad keys show servicer1 -a) ETH1 free >/dev/null
+trace lavad q pairing provider-reputation-details $(lavad keys show servicer1 -a) ETH1 free >/dev/null
 
 echo "Testing dualstaking tx commands"
 wait_count_blocks 1 >/dev/null

testutil/common/tester.go

@@ -922,6 +922,26 @@ func (ts *Tester) QueryPairingProviderEpochCu(provider string, project string, c
 	return ts.Keepers.Pairing.ProvidersEpochCu(ts.GoCtx, msg)
 }
 
+// QueryPairingProviderReputation implements 'q pairing provider-reputation'
+func (ts *Tester) QueryPairingProviderReputation(provider string, chainID string, cluster string) (*pairingtypes.QueryProviderReputationResponse, error) {
+	msg := &pairingtypes.QueryProviderReputationRequest{
+		Provider: provider,
+		ChainID:  chainID,
+		Cluster:  cluster,
+	}
+	return ts.Keepers.Pairing.ProviderReputation(ts.GoCtx, msg)
+}
+
+// QueryPairingProviderReputationDetails implements 'q pairing provider-reputation-details'
+func (ts *Tester) QueryPairingProviderReputationDetails(provider string, chainID string, cluster string) (*pairingtypes.QueryProviderReputationDetailsResponse, error) {
+	msg := &pairingtypes.QueryProviderReputationDetailsRequest{
+		Address: provider,
+		ChainID: chainID,
+		Cluster: cluster,
+	}
+	return ts.Keepers.Pairing.ProviderReputationDetails(ts.GoCtx, msg)
+}
+
 // QueryPairingSubscriptionMonthlyPayout implements 'q pairing subscription-monthly-payout'
 func (ts *Tester) QueryPairingSubscriptionMonthlyPayout(consumer string) (*pairingtypes.QuerySubscriptionMonthlyPayoutResponse, error) {
 	msg := &pairingtypes.QuerySubscriptionMonthlyPayoutRequest{
@@ -1091,6 +1111,15 @@ func (ts *Tester) GetNextMonth(from time.Time) int64 {
 	return utils.NextMonth(from).UTC().Unix()
 }
 
+func (ts *Tester) BlockTimeDefault() time.Duration {
+	return ts.Keepers.Downtime.GetParams(ts.Ctx).DowntimeDuration
+}
+
+func (ts *Tester) EpochTimeDefault() time.Duration {
+	epochBlocks := ts.Keepers.Epochstorage.GetParams(ts.Ctx).EpochBlocks
+	return ts.BlockTimeDefault() * time.Duration(epochBlocks)
+}
+
 func (ts *Tester) AdvanceToBlock(block uint64) {
 	if block < ts.BlockHeight() {
 		panic("AdvanceToBlock: block in the past: " +

utils/convert.go

@@ -1,5 +1,13 @@
 package utils
 
+import "math"
+
+func SafeUint64ToInt64Convert(val uint64) int64 {
+	if val > math.MaxInt64 {
+		val = math.MaxInt64
+	}
+	return int64(val)
+}
 func Btof(b bool) float64 {
 	if b {
 		return 1

utils/math.go

@@ -1,6 +1,14 @@
 package utils
 
-import "golang.org/x/exp/constraints"
+import (
+	"cosmossdk.io/math"
+	sdk "github.com/cosmos/cosmos-sdk/types"
+	"golang.org/x/exp/constraints"
+)
+
+const (
+	DecayFactorNaturalBaseString = "2.71828182845904523536028747135266249775724709369995957496696763"
+)
 
 func Min[T constraints.Ordered](x, y T) T {
 	if x < y {
@@ -15,3 +23,33 @@ func Max[T constraints.Ordered](x, y T) T {
 	}
 	return y
 }
+
+// NaturalBaseExponentFraction calculates an exponent of the
+// natural base e using a sdk.Dec. using the formula: e^(numerator / denominator)
+// since it is not possible to directly calculate a power of a fraction,
+// we're doing it in three steps:
+// 1. Calculate e^numerator
+// 2. Take the denominatorth root
+// 3. Take the reciprocal (if negative=true)
+func NaturalBaseExponentFraction(numerator, denominator int64, negative bool) math.LegacyDec {
+	numeratorUint64 := uint64(numerator)
+	denominatorUint64 := uint64(denominator)
+
+	e := sdk.MustNewDecFromStr(DecayFactorNaturalBaseString)
+
+	// Step 1: Calculate e^a
+	eToA := e.Power(numeratorUint64)
+
+	// Step 2: Take the bth root
+	result, err := eToA.ApproxRoot(denominatorUint64)
+	if err != nil {
+		panic(err)
+	}
+
+	if negative {
+		// Step 3: Take the reciprocal
+		result = sdk.OneDec().Quo(result)
+	}
+
+	return result
+}

x/pairing/README.md

@@ -352,8 +352,13 @@ The pairing module supports the following queries:
 | `list-epoch-payments`     | none  | show all epochPayment objects                  |
 | `list-provider-payment-storage`     | none  | show all providerPaymentStorage objects                 |
 | `list-unique-payment-storage-client-provider`     | none  | show all uniquePaymentStorageClientProvider objects                 |
+| `provider`     | chain-id (string)  | show a provider staked on a specific chain                  |
 | `provider-monthly-payout`     | provider (string)  |  show the current monthly payout for a specific provider                 |
+| `provider-pairing-chance`     | provider (string), chain-id (string)  | show the chance of a provider has to be part of the pairing list for a specific chain                 |
+| `provider-reputation`     | provider (string), chain-id (string), cluster (string)  | show the provider's rank compared to other provider with the same chain-id and cluster by their reputation score                |
+| `provider-reputation-details`     | provider (string), chain-id (string), cluster (string)  | developer query to show the provider's reputation score raw data                |
 | `providers`     | chain-id (string)  | show all the providers staked on a specific chain                  |
+| `providers-epoch-cu`     |   | developer query to list the amount of CU serviced by all the providers every epoch               |
 | `sdk-pairing`     | none  | query used by Lava-SDK to get all the required pairing info                  |
 | `show-epoch-payments`     | index (string)  | show an epochPayment object by index                  |
 | `show-provider-payment-storage`     | index (string)  | show a providerPaymentStorage object by index                  |

x/pairing/client/cli/query.go

@@ -41,6 +41,8 @@ func GetQueryCmd(queryRoute string) *cobra.Command {
 	cmd.AddCommand(CmdSubscriptionMonthlyPayout())
 
 	cmd.AddCommand(CmdProvidersEpochCu())
+	cmd.AddCommand(CmdProviderReputation())
+	cmd.AddCommand(CmdProviderReputationDetails())
 
 	cmd.AddCommand(CmdDebugQuery())
 

x/pairing/client/cli/query_provider_reputation.go

@@ -0,0 +1,65 @@
+package cli
+
+import (
+	"strconv"
+
+	"github.com/cosmos/cosmos-sdk/client"
+	"github.com/cosmos/cosmos-sdk/client/flags"
+	"github.com/lavanet/lava/v4/utils"
+	"github.com/lavanet/lava/v4/x/pairing/types"
+	"github.com/spf13/cobra"
+)
+
+var _ = strconv.Itoa(0)
+
+func CmdProviderReputation() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "provider-reputation [address] [chain-id] [cluster]",
+		Short: "Query for a provider's reputation. Use \"*\" for specify all for chain/cluster.",
+		Args:  cobra.ExactArgs(3),
+		Example: `
+		Reputation of alice for chain ETH1 and the cluster "free":
+		lavad q pairing provider-reputation alice ETH1 free
+
+		Reputation of alice for all chains and the cluster "free":
+		lavad q pairing provider-reputation alice * free
+
+		Reputation of alice for ETH1 and for all clusters:
+		lavad q pairing provider-reputation alice ETH1 *
+
+		Reputation of alice for all chains and for all clusters:
+		lavad q pairing provider-reputation alice * *`,
+		RunE: func(cmd *cobra.Command, args []string) (err error) {
+			clientCtx, err := client.GetClientQueryContext(cmd)
+			if err != nil {
+				return err
+			}
+
+			address, err := utils.ParseCLIAddress(clientCtx, args[0])
+			if err != nil {
+				return err
+			}
+			chainID := args[1]
+			cluster := args[2]
+
+			queryClient := types.NewQueryClient(clientCtx)
+
+			params := &types.QueryProviderReputationRequest{
+				Provider: address,
+				ChainID:  chainID,
+				Cluster:  cluster,
+			}
+
+			res, err := queryClient.ProviderReputation(cmd.Context(), params)
+			if err != nil {
+				return err
+			}
+
+			return clientCtx.PrintProto(res)
+		},
+	}
+
+	flags.AddQueryFlagsToCmd(cmd)
+
+	return cmd
+}

x/pairing/client/cli/query_provider_reputation_details.go

@@ -0,0 +1,65 @@
+package cli
+
+import (
+	"strconv"
+
+	"github.com/cosmos/cosmos-sdk/client"
+	"github.com/cosmos/cosmos-sdk/client/flags"
+	"github.com/lavanet/lava/v4/utils"
+	"github.com/lavanet/lava/v4/x/pairing/types"
+	"github.com/spf13/cobra"
+)
+
+var _ = strconv.Itoa(0)
+
+func CmdProviderReputationDetails() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "provider-reputation-details [address] [chain-id] [cluster]",
+		Short: "Query for a provider's reputation details. Mainly used by developers. Use \"*\" for specify all for chain/cluster.",
+		Args:  cobra.ExactArgs(3),
+		Example: `
+		Reputation details of alice for chain ETH1 and the cluster "free":
+		lavad q pairing provider-reputation-details alice ETH1 free
+
+		Reputation details of alice for all chains and the cluster "free":
+		lavad q pairing provider-reputation-details alice * free
+
+		Reputation details of alice for ETH1 and for all clusters:
+		lavad q pairing provider-reputation-details alice ETH1 *
+
+		Reputation details of alice for all chains and for all clusters:
+		lavad q pairing provider-reputation-details alice * *`,
+		RunE: func(cmd *cobra.Command, args []string) (err error) {
+			clientCtx, err := client.GetClientQueryContext(cmd)
+			if err != nil {
+				return err
+			}
+
+			address, err := utils.ParseCLIAddress(clientCtx, args[0])
+			if err != nil {
+				return err
+			}
+			chainID := args[1]
+			cluster := args[2]
+
+			queryClient := types.NewQueryClient(clientCtx)
+
+			params := &types.QueryProviderReputationDetailsRequest{
+				Address: address,
+				ChainID: chainID,
+				Cluster: cluster,
+			}
+
+			res, err := queryClient.ProviderReputationDetails(cmd.Context(), params)
+			if err != nil {
+				return err
+			}
+
+			return clientCtx.PrintProto(res)
+		},
+	}
+
+	flags.AddQueryFlagsToCmd(cmd)
+
+	return cmd
+}

x/pairing/client/cli/query_providers_epoch_cu.go

@@ -10,10 +10,10 @@ import (
 func CmdProvidersEpochCu() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "providers-epoch-cu",
-		Short: "Query to show the amount of CU serviced by all provider in a specific epoch",
+		Short: "Query to list the amount of CU serviced by all the providers every epoch",
 		Example: `
 		lavad q pairing providers-epoch-cu`,
-		Args: cobra.ExactArgs(1),
+		Args: cobra.ExactArgs(0),
 		RunE: func(cmd *cobra.Command, args []string) (err error) {
 			clientCtx, err := client.GetClientQueryContext(cmd)
 			if err != nil {