Reward signing rewrite

Author: adg-flare

README.md

@@ -114,23 +114,15 @@ gas_price_multiplier = 0
 gas_price_fixed = 50000000000 # 50 * 1e9
 gas_limit = 0
 
-[uptime] # uptime vote configuration - clients.enabled_uptime_voting must be set to true
-signing_window = 2 # (optional) how many epochs in the past wße attempt to sign uptime vote for, default: 2.
-
 [rewards] # reward signing configuration - clients.enabled_reward_signing must be set to true
-# Local folder or URL prefix for retrieving rewards hash files.
-# A full path will be constructed by appending the epoch id and expected file name: <path>/<epochId>/rewards-hash.json
-#
-# Example:
-# - URL prefix: "https://example.com/rewards" -> https://example.com/rewards/2939/rewards-hash.json
-# - Folder: "./rewards" -> ./rewards/2939/rewards-hash.json
+# URL prefix for retrieving reward distribution data. 
+# A full URL will be constructed by appending the epoch id and expected file name: <prefix>/<epochId>/reward-distribution-data.json
 #
-# The rewards hash file is expected to have the following structure:
-# {
-#    "rewardEpochId": <epoch id>,
-#    "noOfWeightBasedClaims": <number of weight-based claims>,
-#    "merkleRoot": "<markle root of all claims for the epoch>"
-# }
-hash_path_prefix = ""
-signing_window = 2 # (optional) how many epochs in the past we attempt to sign rewards for, default: 2.
+# For example, if reward data for an epoch can be retrieved at https://raw.githubusercontent.com/flare-foundation/fsp-rewards/refs/heads/main/songbird/240/reward-distribution-data.json,
+# then the url_prefix should be set to "https://raw.githubusercontent.com/flare-foundation/fsp-rewards/refs/heads/main/songbird"
+url_prefix = ""
+min_reward = 0 # minimum acceptable claim amount in wei for the identity address of this provider, default 0.
+max_reward = 0 # (optional) maximum acceptable claim amount in wei for the identity address of this provider. If 0 or not set, no maximum is enforced.
+retries = 8    # (optional) number of retries for fetching and signing reward data, default: 8.
+retry_interval = "6h" # (optional) interval between retries, default: 6 hours.
 ```

client/config/client.go

@@ -32,7 +32,6 @@ type ClientConfig struct {
 	SubmitGas   GasConfig `toml:"gas_submit"`
 	RegisterGas GasConfig `toml:"gas_register"`
 
-	Uptime  UptimeConfig  `toml:"uptime"`
 	Rewards RewardsConfig `toml:"rewards"`
 }
 
@@ -117,13 +116,14 @@ type GasConfig struct {
 	GasLimit           int      `toml:"gas_limit"`
 }
 
-type UptimeConfig struct {
-	SigningWindow int64 `toml:"signing_window"`
-}
-
 type RewardsConfig struct {
-	PathPrefix    string `toml:"hash_path_prefix"`
-	SigningWindow int64  `toml:"signing_window"`
+	UrlPrefix string `toml:"url_prefix"`
+
+	MinRewardWei *big.Int `toml:"min_reward"`
+	MaxRewardWei *big.Int `toml:"max_reward"`
+
+	Retries       int           `toml:"retries"`
+	RetryInterval time.Duration `toml:"retry_interval"`
 }
 
 func newConfig() *ClientConfig {
@@ -142,11 +142,9 @@ func newConfig() *ClientConfig {
 		},
 		SubmitGas:   GasConfig{GasPriceFixed: big.NewInt(0)},
 		RegisterGas: GasConfig{GasPriceFixed: big.NewInt(0)},
-		Uptime: UptimeConfig{
-			SigningWindow: 2,
-		},
 		Rewards: RewardsConfig{
-			SigningWindow: 2,
+			Retries:       8,
+			RetryInterval: 6 * time.Hour,
 		},
 	}
 }

client/epoch/epoch_client.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	clientConfig "flare-tlc/client/config"
 	flarectx "flare-tlc/client/context"
+	"flare-tlc/client/shared"
 	"flare-tlc/config"
 	"flare-tlc/logger"
 	"flare-tlc/utils/chain"
@@ -34,7 +35,6 @@ type EpochClient struct {
 	rewardsSigningEnabled bool
 
 	rewardsConfig *clientConfig.RewardsConfig
-	uptimeConfig  *clientConfig.UptimeConfig
 }
 
 func NewEpochClient(ctx flarectx.ClientContext) (*EpochClient, error) {
@@ -106,7 +106,6 @@ func NewEpochClient(ctx flarectx.ClientContext) (*EpochClient, error) {
 		uptimeVotingEnabled:   cfg.Clients.EnabledUptimeVoting,
 		rewardsSigningEnabled: cfg.Clients.EnabledRewardSigning,
 		rewardsConfig:         &cfg.Rewards,
-		uptimeConfig:          &cfg.Uptime,
 	}, nil
 }
 
@@ -135,11 +134,11 @@ func (c *EpochClient) RunContext(ctx context.Context) error {
 	}
 	if c.uptimeVotingEnabled {
 		logger.Info("Waiting for SignUptimeVoteEnabled event to start uptime vote signing")
-		uptimeEnabledListener = c.systemsManagerClient.SignUptimeVoteEnabledListener(c.db, epoch, c.uptimeConfig.SigningWindow)
+		uptimeEnabledListener = c.systemsManagerClient.SignUptimeVoteEnabledListener(c.db, epoch)
 	}
 	if c.rewardsSigningEnabled {
 		logger.Info("Waiting for UptimeVoteSigned event to start rewards signing")
-		uptimeSignedListener = c.systemsManagerClient.UptimeVoteSignedListener(c.db, epoch, c.rewardsConfig.SigningWindow)
+		uptimeSignedListener = c.systemsManagerClient.UptimeVoteSignedListener(c.db, epoch)
 	}
 
 	for {
@@ -156,7 +155,6 @@ func (c *EpochClient) RunContext(ctx context.Context) error {
 		case uptimeVoteSigned := <-uptimeSignedListener:
 			logger.Info("Uptime vote threshold reached for epoch %v, signing rewards", uptimeVoteSigned.RewardEpochId)
 			c.signRewards(uptimeVoteSigned.RewardEpochId)
-
 		case <-ctx.Done():
 			return ctx.Err()
 		}
@@ -195,7 +193,6 @@ func (c *EpochClient) signPolicy(epochId *big.Int, policy []byte) {
 }
 
 func (c *EpochClient) signUptimeVote(epochId *big.Int) {
-	logger.Info("SignUptimeVoteEnabled event emitted for epoch %v, signing uptime vote", epochId)
 	signUptimeVoteResult := <-c.systemsManagerClient.SignUptimeVote(epochId)
 	if signUptimeVoteResult.Success {
 		logger.Info("SignUptimeVote completed")
@@ -219,17 +216,54 @@ func (c *EpochClient) isFutureEpoch(epochId *big.Int) bool {
 	return true
 }
 
+// signRewards signs the reward claim merkle root for the given epoch.
+//
+// Once uptime signing is completed, data providers can start signing the reward hash for the epoch.
+// The end goal is that every data provider calculates reward hash by themselves and signs it. While rewarding logic
+// is still in flux, there is an interim solution where reward data is calculated & published centrally, and data
+// providers independently verify and sign the hash.
+//
+// Here signRewards first retrieves the reward claim data file from the configured URL. It verifies the provided
+// merkle root matches the list of claims, checks there is a reward claim for the identity address of this provider,
+// with reward amount within expected bounds.
+//
+// If all checks pass, it signs the merkle root and sends the signature to the SystemsManager contract.
+//
+// Since reward claim data is currently published manually, and it might take a day or so for the data to be available,
+// a retry mechanism is employed with a large retry interval (configurable).
 func (c *EpochClient) signRewards(epochId *big.Int) {
-	logger.Info("Signing rewards for epoch %v", epochId)
-	hash, weightClaims, err := getRewardsHash(epochId, c.rewardsConfig)
-	if err != nil {
-		logger.Error("error obtaining reward hash data for epoch %v, restart client to retry: %s", epochId, err)
-		return
-	}
-	signingResult := <-c.systemsManagerClient.SignRewards(epochId, hash, weightClaims)
-	if signingResult.Success {
-		logger.Info("SignRewards completed")
-	} else {
-		logger.Error("SignRewards failed %s", signingResult.Message)
-	}
+	res := shared.ExecuteWithRetryAttempts(func(i int) (*struct{}, error) {
+		if c.systemsManagerClient.IsRewardHashSigned(epochId) {
+			return nil, nil
+		}
+
+		logger.Info("Signing rewards for epoch %v, attempt %d", epochId, i)
+
+		data, err := fetchRewardData(epochId, c.rewardsConfig)
+		if data == nil {
+			return nil, errors.New("no reward data found")
+		}
+		if err != nil {
+			return nil, errors.Wrapf(err, "unable to fetch reward data for epoch %d", epochId)
+		}
+		hash, weightClaims, err := verifyRewardData(epochId, c.identityAddress, data, c.rewardsConfig)
+		if err != nil {
+			return nil, errors.Wrapf(err, "reward data verification for epoch %d failed", epochId)
+		}
+		signingResult := <-c.systemsManagerClient.SignRewards(epochId, hash, weightClaims)
+		if !signingResult.Success {
+			return nil, errors.Errorf("unable to send reward signature")
+		}
+		return nil, nil
+	}, c.rewardsConfig.Retries, c.rewardsConfig.RetryInterval)
+
+	// The retry loop may run four hours until the reward data is published, so we don't block for result here.
+	go func() {
+		status := <-res
+		if status.Success {
+			logger.Info("Signing rewards for epoch %v completed", epochId)
+		} else {
+			logger.Info("Signing rewards for epoch %v failed: %s", epochId, status.Message)
+		}
+	}()
 }

client/epoch/epoch_client_test.go

@@ -385,7 +385,7 @@ func (c testRegistryClient) RegisterVoter(
 	}, 1, 0)
 }
 
-func (c testSystemsManagerClient) SignUptimeVoteEnabledListener(db epochClientDB, epoch *utils.Epoch, i int64) <-chan *system.FlareSystemsManagerSignUptimeVoteEnabled {
+func (c testSystemsManagerClient) SignUptimeVoteEnabledListener(db epochClientDB, epoch *utils.Epoch) <-chan *system.FlareSystemsManagerSignUptimeVoteEnabled {
 	return make(chan *system.FlareSystemsManagerSignUptimeVoteEnabled)
 }
 
@@ -395,7 +395,7 @@ func (c testSystemsManagerClient) SignUptimeVote(b *big.Int) <-chan shared.Execu
 	}, 1, 0)
 }
 
-func (c testSystemsManagerClient) UptimeVoteSignedListener(db epochClientDB, epoch *utils.Epoch, window int64) <-chan *system.FlareSystemsManagerUptimeVoteSigned {
+func (c testSystemsManagerClient) UptimeVoteSignedListener(db epochClientDB, epoch *utils.Epoch) <-chan *system.FlareSystemsManagerUptimeVoteSigned {
 	return make(chan *system.FlareSystemsManagerUptimeVoteSigned)
 }
 
@@ -404,3 +404,7 @@ func (c testSystemsManagerClient) SignRewards(b *big.Int, hash *common.Hash, cla
 		return nil, nil
 	}, 1, 0)
 }
+
+func (c testSystemsManagerClient) IsRewardHashSigned(b *big.Int) bool {
+	return false
+}