feat: implement node rewards calculation and API endpoint #64

0oM4R · 2025-06-12T17:04:07Z

Description

This PR introduces a new API endpoint to calculate real-time node rewards based on node resources and uptime reports.

Please note that the network usage is not included
And please consider those concerns, comment

Changes

New Endpoint:
GET /nodes/{node_id}/rewards
Returns: Rewards
New Handler:
getNodeRewardsHandler – handles input validation and response logic.

New Reward Logic:
Added a pkg/server/rewards.go file with the logic to:
- Get uptime reports for the current month
- Calculate uptime percentage
- Apply reward formula
- Return reward values (or zeroes if uptime is too low)

Swagger Update:
API documentation updated with the new endpoint and response schema.

Tests

Add unit tests, create a fake node, and submit some reports

Related Issues

support calculating node rewards #63

Checklist

Tests included
Build pass
Documentation
Code format and docstring

… uptime percentage

node-registrar/pkg/server/handlers.go

node-registrar/pkg/server/rewards.go

…intainability

…d add test suite

… tracking

…se explanation

…yReward struct

node-registrar/pkg/server/handlers.go

node-registrar/test/main.go

node-registrar/pkg/server/handlers.go

…yReward struct

node-registrar/pkg/server/rewards_test.go

Eslam-Nawara · 2025-06-29T11:50:00Z

node-registrar/pkg/server/rewards_test.go

+
+	// Use precise floating point comparison
+	const delta = 1e-9 // Very small acceptable difference
+	assert.InDelta(t, expected.FarmerReward, got.FarmerReward, delta)


all this values are rounded no?

node-registrar/pkg/server/rewards_test.go

node-registrar/client/node.go

…v4-sdk-go into development_rewards

…n handler

…ed value checks in rewards tests

…hecks

…ions

node-registrar/pkg/server/handlers.go

node-registrar/pkg/server/rewards_test.go

Eslam-Nawara · 2025-07-14T09:30:23Z

node-registrar/pkg/server/rewards_test.go

+	assert.Equal(t, expected.FarmerReward, got.FarmerReward)
+	assert.Equal(t, expected.TfReward, got.TfReward)
+	assert.Equal(t, expected.FpReward, got.FpReward)
+	assert.Equal(t, expected.Total, got.Total)
+	assert.Equal(t, expected.UpTimePercentage, got.UpTimePercentage)


why not just use assert.Equal(t, expected, got)

why not just use assert.Equal(t, expected, got)

Is that enough, or should we use something like deep equal?

assert.Equal does the same job

node-registrar/pkg/server/rewards_test.go

…o into development_rewards

…of math.Pow

…time computation

…wards test

Eslam-Nawara · 2025-07-20T14:59:31Z

node-registrar/pkg/server/rewards.go

+}
+
+// calculateCapacityReward calculates the reward for a node based on its capacity and uptime, during a specific period.
+func CalculateCapacityReward(capacity db.Resources, reports []db.UptimeReport, periodStart, periodEnd time.Time) (Reward, error) {


this function is not used outside the server pkg, so no need to be exported

Eslam-Nawara · 2025-07-20T15:00:46Z

node-registrar/pkg/server/rewards_test.go

+	assert.Equal(t, expected.FarmerReward, got.FarmerReward)
+	assert.Equal(t, expected.TfReward, got.TfReward)
+	assert.Equal(t, expected.FpReward, got.FpReward)
+	assert.Equal(t, expected.Total, got.Total)
+	assert.Equal(t, expected.UpTimePercentage, got.UpTimePercentage)


assert.Equal does the same job

Eslam-Nawara · 2025-07-20T15:11:57Z

node-registrar/pkg/server/rewards.go

+		return Reward{}, ErrReportsNotInAscOrder
+	}
+
+	upTimePercentage := calculatePercentage(periodEnd.Sub(periodStart), downtimeSinceLastReportTimestamp(reports[len(reports)-1].Timestamp, periodEnd))


percentage of what?

Eslam-Nawara · 2025-07-20T15:12:20Z

node-registrar/pkg/server/rewards.go

+
+	upTimePercentage := calculatePercentage(periodEnd.Sub(periodStart), downtimeSinceLastReportTimestamp(reports[len(reports)-1].Timestamp, periodEnd))
+
+	return computeCapacityRewardWithUptime(capacity, upTimePercentage)


calculate instead of compute

Eslam-Nawara · 2025-07-20T16:23:39Z

node-registrar/pkg/server/rewards.go

+// calculateBaseCapacityReward calculates the base reward from node capacity without applying uptime.
+func calculateBaseCapacityReward(capacity db.Resources) float64 {
+	mruReward := bytesToGB(capacity.MRU) * MemoryRewardPerGB
+	sruReward := bytesToTB(capacity.SRU) * SsdRewardPerTB
+	hruReward := bytesToTB(capacity.HRU) * HddRewardPerTB
+
+	return mruReward + sruReward + hruReward
+}
+
+// calculateTotalReward calculates the total reward based on node capacity and uptime percentage.
+// It first calculates the base capacity reward and then applies the uptime percentage.
+func calculateTotalReward(capacity db.Resources, upTimePercentage float64) float64 {
+	baseReward := calculateBaseCapacityReward(capacity)
+	return baseReward * (upTimePercentage / 100)
+}


I don't think we need two functions for this, the logic of calculateBaseCapacityReward can be moved to calculate totalReward instead

Eslam-Nawara · 2025-07-21T09:40:18Z

node-registrar/pkg/server/rewards.go

+	FirstPeriodStartTimestamp int64 = 1522501000
+
+	// Uptime events are supposed to happen every 40 minutes.
+	// Here we set this to one hour (3600 sec) to allow some room.
+	UptimeEventsInterval = 3600
+
+	// The duration of a standard period, as used by the minting payouts, in seconds.
+	// Calculated as: 24 hours * 60 minutes * 60 seconds * (365*3 + 366*2) / 60 periods
+	StandardPeriodDuration int64 = 24 * 60 * 60 * (365*3 + 366*2) / 60


are we using those consts outside the pkg? if no we should not export them

Eslam-Nawara · 2025-07-21T10:19:06Z

node-registrar/pkg/server/rewards.go

+	periodStart := referenceTime.Unix() - periodOffset
+	return time.Unix(periodStart, 0)


you can use referenceTime.Add(-time.Duration(periodOffset)) instead

0oM4R added 10 commits June 12, 2025 20:03

feat: implement node rewards calculation and API endpoint

538c347

test: add test case for uptime percentage with decimal value

3ed761e

refactor: replace error string with proper error variable for invalid…

929bad7

… uptime percentage

docs: mention that the duration in seconds

bdcd279

feat: implement node uptime calculation based on report history

1dcc431

feat: add uptime percentage to rewards struct

66b2a66

docs: add swagger docs for the rewards endpoint

0ea416e

feat: show uptime percentage in the response of no rewards

f60aa13

fix: rename reward endpoint to rewards

38e8082

feat: truncate reward values to 3 decimal places

eb4aeca

0oM4R marked this pull request as ready for review June 22, 2025 11:27

0oM4R requested review from mariobassem, ashraffouda, rawdaGastan, Omarabdul3ziz, AbdelrahmanElawady, xmonader, sameh-farouk and Eslam-Nawara as code owners June 22, 2025 11:27

Eslam-Nawara reviewed Jun 22, 2025

View reviewed changes

0oM4R added 10 commits June 23, 2025 12:03

feat: add uptime percentage to reward calculation in tests

b39f7f7

refactor: rename constants and functions to follow Go naming conventions

41c2c64

Fix tests: pass duration as time.duration

6c5993c

refactor: rename and split reward calculation functions for better ma…

d80cbe0

…intainability

feat: improve error handling for node uptime reports and add test cases

0c6094d

refactor: enhance loops

04e5a9a

refactor: extract reward calculation logic into separate functions an…

ceff122

…d add test suite

test: add comprehensive test suite for rewards calculation and uptime…

5e9f390

… tracking

revert adding main.go

f538295

docs: simplify uptime percentage calculation documentation with conci…

81906f9

…se explanation

0oM4R and others added 4 commits June 24, 2025 18:19

WIP: add rewards tests in client

395a4fc

remove extra println

55e7ea8

tests: add more test cases for the rewards

c4f1136

refactor: standardize reward field names and JSON tags in NodeCapacit…

10c4a79

…yReward struct

Eslam-Nawara reviewed Jun 29, 2025

View reviewed changes

node-registrar/pkg/server/handlers.go Outdated Show resolved Hide resolved

node-registrar/test/main.go Outdated Show resolved Hide resolved

node-registrar/pkg/server/handlers.go Outdated Show resolved Hide resolved

Eslam-Nawara and others added 5 commits June 29, 2025 15:26

fix node tests in client

e5e481c

WIP: add rewards tests in client

2465abc

remove extra println

2b5f964

tests: add more test cases for the rewards

02e4c78

refactor: standardize reward field names and JSON tags in NodeCapacit…

6646f65

…yReward struct

Eslam-Nawara force-pushed the development_rewards branch from 10c4a79 to 6646f65 Compare June 29, 2025 12:26

Eslam-Nawara reviewed Jun 29, 2025

View reviewed changes

0oM4R added 8 commits June 30, 2025 12:38

Merge branch 'development_rewards' of github.com:threefoldtech/tfgrid…

56109d3

…v4-sdk-go into development_rewards

revert: remove the test file

d0ce507

fix: use errors.Is() for proper error comparison in uptime calculatio…

ff3487f

…n handler

refactor: replace floating point delta comparisons with exact truncat…

b407b77

…ed value checks in rewards tests

test: replace InDelta with Equal for reward distribution percentage c…

cdd305f

…hecks

refactor: simplify test assertions using require and assert packages

6a71bc3

fix: handle nil response in node rewards request

2ae9121

refactor: simplify error handling in node rewards and uptime calculat…

311f49d

…ions

0oM4R requested a review from Eslam-Nawara July 8, 2025 10:39

Eslam-Nawara reviewed Jul 14, 2025

View reviewed changes

0oM4R added 6 commits July 14, 2025 15:03

Merge branch 'development' of github.com:threefoldtech/tfgridv4-sdk-g…

b41cddc

…o into development_rewards

lint

724b052

refactor: simplify bytes conversion using explicit constants instead …

036a1b2

…of math.Pow

refactor: consolidate reward calculation into single function with up…

f094176

…time computation

test: replace assert with require for consistent error checking in re…

acfb746

…wards test

refactor: simplify reward test assertions by comparing entire struct

9d4fd14

0oM4R requested a review from Eslam-Nawara July 14, 2025 15:30

Eslam-Nawara reviewed Jul 21, 2025

View reviewed changes


		upTimePercentage := calculatePercentage(periodEnd.Sub(periodStart), downtimeSinceLastReportTimestamp(reports[len(reports)-1].Timestamp, periodEnd))

		return computeCapacityRewardWithUptime(capacity, upTimePercentage)

		periodStart := referenceTime.Unix() - periodOffset
		return time.Unix(periodStart, 0)

feat: implement node rewards calculation and API endpoint #64

Are you sure you want to change the base?

feat: implement node rewards calculation and API endpoint #64

Uh oh!

Conversation

0oM4R commented Jun 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Tests

Related Issues

Checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

0oM4R commented Jun 12, 2025 •

edited

Loading