A few more edits

go.mod

@@ -82,6 +82,7 @@ require (
 	cosmossdk.io/x/tx v0.13.4
 	github.com/jhump/protoreflect v1.16.0
 	github.com/mitchellh/mapstructure v1.5.0
+	go.uber.org/mock v0.5.0
 )
 
 require (

go.sum

@@ -1211,6 +1211,8 @@ go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0
 go.uber.org/goleak v1.1.10/go.mod h1:8a7PlsEVH3e/a/GLqe5IIrQx6GzcnRmZEufDUTk4A7A=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
 go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
+go.uber.org/mock v0.5.0 h1:KAMbZvZPyBPWgD14IrIQ38QCyjwpvVVV6K/bHl1IwQU=
+go.uber.org/mock v0.5.0/go.mod h1:ge71pBPLYDk7QIi1LupWxdAykm7KIEFchiOqd6z7qMM=
 go.uber.org/multierr v1.1.0/go.mod h1:wR5kodmAFQ0UK8QlbwjlSNy0Z68gJhDJUG5sjR94q/0=
 go.uber.org/multierr v1.3.0/go.mod h1:VgVr7evmIr6uPjLBxg28wmKNXyqE9akIJ5XnfpiKl+4=
 go.uber.org/multierr v1.6.0/go.mod h1:cdWPpRnG4AhwMwsgIHip0KRBQjJy5kYEpYjJxpXp9iU=

proto/poktroll/application/types.proto

@@ -14,30 +14,37 @@ import "cosmos_proto/cosmos.proto";
 
 import "poktroll/shared/service.proto";
 
-// Application defines the type used to store an onchain definition and state for an application
+// Application represents the on-chain definition and state of an application
 message Application {
-  string address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // The Bech32 address of the application.
-  cosmos.base.v1beta1.Coin stake = 2; // The total amount of uPOKT the application has staked
-  // CRITICAL_DEV_NOTE: The number of service_configs must be EXACTLY ONE.
-  // This prevents applications from over-servicing.
-  // The field is kept repeated (a list) for both legacy and future logic reaosns.
-  // References:
-  //  - https://github.com/pokt-network/poktroll/pull/750#discussion_r1735025033
-  //  - https://www.notion.so/buildwithgrove/Off-chain-Application-Stake-Tracking-6a8bebb107db4f7f9dc62cbe7ba555f7
-  repeated poktroll.shared.ApplicationServiceConfig service_configs = 3; // The list of services this appliccation is configured to request service for
+  // Bech32 address of the application
+  string address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+
+  // Total amount of staked uPOKT
+  cosmos.base.v1beta1.Coin stake = 2;
+
+  // CRITICAL: Must contain EXACTLY ONE service config
+  // Kept as repeated for legacy and future compatibility
+  // Refs:
+  //   - https://github.com/pokt-network/poktroll/pull/750#discussion_r1735025033
+  //   - https://www.notion.so/buildwithgrove/Off-chain-Application-Stake-Tracking-6a8bebb107db4f7f9dc62cbe7ba555f7
+  repeated poktroll.shared.ApplicationServiceConfig service_configs = 3;
+
   // TODO_BETA(@bryanchriswhite): Rename `delegatee_gateway_addresses` to `gateway_addresses_delegated_to`.
   // Ensure to rename all relevant configs, comments, variables, function names, etc as well.
-  repeated string delegatee_gateway_addresses = 4 [(cosmos_proto.scalar) = "cosmos.AddressString", (gogoproto.nullable) = false]; // The Bech32 encoded addresses for all delegatee Gateways, in a non-nullable slice
-  // A map from sessionEndHeights to a list of Gateways.
-  // The key is the height of the last block of the session during which the
-  // respective undelegation was committed.
-  // The value is a list of gateways being undelegated from.
+  // Non-nullable list of Bech32 encoded delegatee Gateway addresses
+  repeated string delegatee_gateway_addresses = 4 [(cosmos_proto.scalar) = "cosmos.AddressString", (gogoproto.nullable) = false];
+
+  // Mapping of session end heights to gateways being undelegated from
+  // Key: Height of the last block of the session when undelegation was committed
+  // Value: List of gateways being undelegated from
   // TODO_DOCUMENT(@red-0ne): Need to document the flow from this comment
   // so its clear to everyone why this is necessary; https://github.com/pokt-network/poktroll/issues/476#issuecomment-2052639906.
   map<uint64, UndelegatingGatewayList> pending_undelegations = 5 [(gogoproto.nullable) = false];
-  // The end height of the session at which an application initiated its unstaking process.
-  // If the application did not unstake, this value will be 0.
+
+  // Session end height when application initiated unstaking (0 if not unstaking)
   uint64 unstake_session_end_height = 6;
+
+  // Information about pending application transfers
   PendingApplicationTransfer pending_transfer = 7;
 }
 

proto/poktroll/shared/service.proto

@@ -58,7 +58,7 @@ message SupplierEndpoint {
 // ServiceRevenueShare message to hold revenue share configuration details
 message ServiceRevenueShare {
   // 2 was reserved in #1028 during the change of rev_share_percentage from float to uint64
-  // TODO_TECHDEBT: Investigate why we can't use a double or float: https://github.com/pokt-network/poktroll/actions/runs/12832899448/job/35787150432?pr=1028
+  // TODO_TECHDEBT(#1033): Investigate if we can use a double instead.
   reserved 2;
 
   string address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // The Bech32 address of the revenue share recipient

proto/poktroll/shared/supplier.proto

@@ -10,24 +10,28 @@ import "cosmos/base/v1beta1/coin.proto";
 import "poktroll/shared/service.proto";
 import "gogoproto/gogo.proto";
 
-// Supplier is the type defining the actor in Pocket Network that provides RPC services.
+// Supplier represents an actor in Pocket Network that provides RPC services
 message Supplier {
-  // The address of the owner (i.e. staker, custodial) that owns the funds for staking.
-  // By default, this address is the one that receives all the rewards unless owtherwise specified.
-  // This property cannot be updated by the operator.
-  string owner_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // Bech32 cosmos address
-  // The operator address of the supplier operator (i.e. the one managing the offchain server).
-  // The operator address can update the supplier's configurations excluding the owner address.
-  // This property does not change over the supplier's lifespan, the supplier must be unstaked
-  // and re-staked to effectively update this value.
-  string operator_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // Bech32 cosmos address
-  cosmos.base.v1beta1.Coin stake = 3; // The total amount of uPOKT the supplier has staked
-  repeated SupplierServiceConfig services = 4; // The service configs this supplier can support
-  // The session end height at which an actively unbonding supplier unbonds its stake.
-  // If the supplier did not unstake, this value will be 0.
+  // Owner address that controls the staked funds and receives rewards by default
+  // Cannot be updated by the operator
+  string owner_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+
+  // Operator address managing the off-chain server
+  // Immutable for supplier's lifespan - requires unstake/re-stake to change
+  // Can update supplier configs except owner address
+  string operator_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+
+  // Total amount of staked uPOKT
+  cosmos.base.v1beta1.Coin stake = 3;
+
+  // List of service configurations supported by this supplier
+  repeated SupplierServiceConfig services = 4;
+
+  // Session end height when supplier initiated unstaking (0 if not unstaking)
   uint64 unstake_session_end_height = 5;
-  // services_activation_heights_map is a map of serviceIds to the height at
-  // which the staked supplier will become active for that service.
-  // Activation heights are session start heights.
+
+  // Mapping of serviceIds to their activation heights
+  // Key: serviceId
+  // Value: Session start height when supplier becomes active for the service
   map<string, uint64> services_activation_heights_map = 6;
 }