[Gateway] Implement gateway unbonding period #1062

red-0ne · 2025-02-10T09:03:21Z

Summary

This pull request introduces a Gateway unbonding period, preventing gateways from immediately unstaking after a MsgUnstakeGateway message is committed.

Primary Changes:

Updated the UnstakeGateway message handler to mark a gateway as unbonding instead of removing it.
Added EventGatewayUnbondingBegin and EventGatewayUnbondingEnd events.
Implemented the EndBlockerUnbondGateways keeper method to finalize gateways unbonding.

Secondary changes:

Introduced the GatewayUnbondingPeriodSessions shared governance parameter.
Updated unit and E2E tests to reflect these changes.

Issue

Issue: [Gateway] Gateway Unbonding Periods #731

Type of change

Select one or more from the following:

New feature, functionality or library
Consensus breaking; add the consensus-breaking label if so. See [Infra] Automatically add the consensus-breaking label #791 for details
Bug fix
Code health or cleanup
Documentation
Other (specify)

Sanity Checklist

I have updated the GitHub Issue assignees, reviewers, labels, project, iteration and milestone
For docs, I have run make docusaurus_start
For code, I have run make go_develop_and_test and make test_e2e
For code, I have added the devnet-test-e2e label to run E2E tests in CI
For configurations, I have update the documentation
I added TODOs where applicable

Olshansk

@red-0ne I apoligize for the "terse" and "short" comments in advance. My intention was to get through the whole PR at once.

Two major things I called out:

A couple of verification tests
Updating applications

Other than that, it's the usual nits / edits.

For the comments that are repetitive, feel free to resolve and consolidate the conversation in one thread.

Olshansk · 2025-02-13T00:41:49Z

proto/poktroll/gateway/event.proto

-  Gateway gateway = 1 [(gogoproto.jsontag) = "gateway"];
-  // The end height of the session in which gateway was unstaked.
-  int64 session_end_height = 2 [(gogoproto.jsontag) = "session_end_height"];
+// EventGatewayUnbondingBegin is emitted when a gateway begins unbonding.


Make sure to add the consensus-breaking label for stuff like this.

cc @okdas as a reminder/need to automate this (ticket & PR are already in flight)

Olshansk · 2025-02-13T00:42:40Z

proto/poktroll/gateway/types.proto

  string address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // The Bech32 address of the gateway
  cosmos.base.v1beta1.Coin stake = 2; // The total amount of uPOKT the gateway has staked
+  // Session end height at which the gateway initiated unstaking (0 if not unstaking)
+  uint64 unstake_session_end_height = 3;


Suggested change

string address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // The Bech32 address of the gateway

cosmos.base.v1beta1.Coin stake = 2; // The total amount of uPOKT the gateway has staked

// Session end height at which the gateway initiated unstaking (0 if not unstaking)

uint64 unstake_session_end_height = 3;

// The Bech32 address of the gateway

string address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

// The total amount of uPOKT the gateway has staked

cosmos.base.v1beta1.Coin stake = 2;

// Session end height at which the gateway initiated unstaking (0 if not unstaking)

uint64 unstake_session_end_height = 3;

We're all learning whats easier to read

Olshansk · 2025-02-13T00:43:11Z

proto/poktroll/shared/params.proto

@@ -44,4 +44,9 @@ message Params {
  // The amount of upokt that a compute unit should translate to when settling a session.
  // DEV_NOTE: This used to be under x/tokenomics but has been moved here to avoid cyclic dependencies.
  uint64 compute_units_to_tokens_multiplier = 9 [(gogoproto.jsontag) = "compute_units_to_tokens_multiplier", (gogoproto.moretags) = "yaml:\"compute_units_to_tokens_multiplier\""];
+  // gateway_unbonding_period_sessions is the number of sessions that a gateway must wait after


Suggested change

// gateway_unbonding_period_sessions is the number of sessions that a gateway must wait after

// gateway_unbonding_period_sessions is the number of sessions that a gateway must wait after

Olshansk · 2025-02-13T00:53:51Z

proto/poktroll/gateway/event.proto

+// EventGatewayUnbondingEnd is emitted when a gateway has completed
+// unbonding.


Suggested change

// EventGatewayUnbondingEnd is emitted when a gateway has completed

// unbonding.

// EventGatewayUnbondingEnd is emitted when a gateway has completed unbonding.

Olshansk · 2025-02-13T00:57:01Z

proto/poktroll/shared/params.proto

+  // gateway_unbonding_period_sessions is the number of sessions that a gateway must wait after
+  // unstaking before their staked assets are moved to its account balance.
+  // Onchain business logic requires, and ensures, that the corresponding block count of the
+  // gateway unbonding period will exceed the end of its corresponding proof window close height.


Why are we talking about proof windows here?

Olshansk · 2025-02-13T02:00:33Z

x/gateway/keeper/unbond_gateways.go

+	)
+	if err != nil {
+		logger.Error(fmt.Sprintf(
+			"could not send %v coins from module %s to account %s due to %v",


Suggested change

"could not send %v coins from module %s to account %s due to %v",

"could not send %v coins from module %s to gateway account %s due to %v",

Olshansk · 2025-02-13T02:01:28Z

x/gateway/keeper/unbond_gateways.go

+		if err := k.UnbondGateway(ctx, &gateway); err != nil {
+			return err
+		}
+


Don't we need to also update applications here?

Olshansk · 2025-02-13T02:03:15Z

x/gateway/keeper/msg_server_unstake_gateway_test.go

 	"github.com/pokt-network/poktroll/x/gateway/keeper"
 	"github.com/pokt-network/poktroll/x/gateway/types"
+	sharedtypes "github.com/pokt-network/poktroll/x/shared/types"
 )

 func TestMsgServer_UnstakeGateway_Success(t *testing.T) {


I'd love to see two more tests (use AI to help you):

func TestMsgServer_UnstakeGateway_DelegatingApplicationCheck_Success

func TestMsgServer_UnstakeGatewayAndRestake_DelegatingApplicationCheck_Success

Olshansk · 2025-02-13T02:04:34Z

x/gateway/types/gateway.go

+// IsActive returns whether the gateway is allowed to handle services at the
+// given query height.
+// A gateway that has not submitted an unstake message is always active.
+// A gateway that has submitted an unstake message is active until the end of
+// the session containing the height at which unstake message was submitted.


Suggested change

// IsActive returns whether the gateway is allowed to handle services at the

// given query height.

// A gateway that has not submitted an unstake message is always active.

// A gateway that has submitted an unstake message is active until the end of

// the session containing the height at which unstake message was submitted.

// IsActive returns whether the gateway is allowed to handle services at the given query height.

//

// Gateway activity rules:

// - Gateway without unstake message: Always active

// - Gateway with unstake message: Active until end of session containing unstake height

Olshansk · 2025-02-13T02:11:43Z

x/gateway/keeper/msg_server_unstake_gateway.go

+	// Mark the gateway as unstaking by recording the height at which it should
+	// no longer be able to process requests.
+	// The gateway MAY continue to process requests until the end of the current
+	// session. After that, the gateway will be considered inactive.


Suggested change

// Mark the gateway as unstaking by recording the height at which it should

// no longer be able to process requests.

// The gateway MAY continue to process requests until the end of the current

// session. After that, the gateway will be considered inactive.

// Mark the gateway as unstaking by recording its deactivation height.

//

// Processing rules:

// - Gateway MAY continue processing requests until current session ends

// - After session end: Gateway becomes inactive

red-0ne added 2 commits February 10, 2025 09:08

feat: Implement gateway unbonding

50cf290

Merge remote-tracking branch 'origin/main' into feat/gateway-unbonding

51b0736

red-0ne added gateway Changes related to the Gateway actor on-chain On-chain business logic labels Feb 10, 2025

red-0ne added this to the Beta TestNet Iteration milestone Feb 10, 2025

red-0ne requested review from bryanchriswhite and Olshansk February 10, 2025 09:03

red-0ne self-assigned this Feb 10, 2025

Merge branch 'main' into feat/gateway-unbonding

206ccf8

Olshansk requested changes Feb 13, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Gateway] Implement gateway unbonding period #1062

[Gateway] Implement gateway unbonding period #1062

red-0ne commented Feb 10, 2025

Olshansk left a comment

Olshansk Feb 13, 2025

Olshansk Feb 13, 2025

Olshansk Feb 13, 2025

Olshansk Feb 13, 2025

Olshansk Feb 13, 2025

Olshansk Feb 13, 2025

Olshansk Feb 13, 2025

Olshansk Feb 13, 2025

Olshansk Feb 13, 2025

Olshansk Feb 13, 2025

Olshansk Feb 13, 2025

	// gateway_unbonding_period_sessions is the number of sessions that a gateway must wait after

	// gateway_unbonding_period_sessions is the number of sessions that a gateway must wait after

		// EventGatewayUnbondingEnd is emitted when a gateway has completed
		// unbonding.

	"could not send %v coins from module %s to account %s due to %v",
	"could not send %v coins from module %s to gateway account %s due to %v",

[Gateway] Implement gateway unbonding period #1062

Are you sure you want to change the base?

[Gateway] Implement gateway unbonding period #1062

Conversation

red-0ne commented Feb 10, 2025

Summary

Primary Changes:

Secondary changes:

Issue

Type of change

Sanity Checklist

Olshansk left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment