[Tokenomics] Refactoring claim settlement to enable Token Logic Modules

Makefile

@@ -747,13 +747,13 @@ acc_balance_query: ## Query the balance of the account specified (make acc_balan
 
 .PHONY: acc_balance_query_modules
 acc_balance_query_modules: ## Query the balance of the network level module accounts
-	@echo "### Application ###"
+	@echo "### Application Module ###\n"
 	make acc_balance_query ACC=$(APPLICATION_MODULE_ADDRESS)
-	@echo "### Supplier ###"
+	@echo "### Supplier Module ###\n"
 	make acc_balance_query ACC=$(SUPPLIER_MODULE_ADDRESS)
-	@echo "### Gateway ###"
+	@echo "### Gateway Module ###\n"
 	make acc_balance_query ACC=$(GATEWAY_MODULE_ADDRESS)
-	@echo "### Service ###"
+	@echo "### Service Module ###\n"
 	make acc_balance_query ACC=$(SERVICE_MODULE_ADDRESS)
 
 .PHONY: acc_balance_query_app1

config.yml

@@ -87,9 +87,21 @@ validators:
 # We can persist arbitrary genesis values via 1 to 1 mapping to genesis.json
 genesis:
   app_state:
+    # https://docs.cosmos.network/main/build/modules/mint
     mint:
       params:
         mint_denom: upokt
+        # Note that in Pocket Network, the majority of the inflation/deflation
+        # comes from the utility of network, not just the validators that
+        # secure it. Therefore, the inflation params of x/mint are set to 0.
+        # See x/tokenomics for all details related to token inflation.
+        inflation_rate_change: "0.0"
+        inflation_max: "0.0"
+        inflation_min: "0.0"
+        # These parameters are included for posterity but commented out for clarity
+        # goal_bonded: "NA"
+        # blocks_per_year: "NA"
+        # max_supply: "NA"
     staking:
       params:
         bond_denom: upokt

go.mod

@@ -125,6 +125,7 @@ require (
 	github.com/cockroachdb/redact v1.1.5 // indirect
 	github.com/cockroachdb/tokenbucket v0.0.0-20230807174530-cc333fc44b06 // indirect
 	github.com/cometbft/cometbft-db v0.9.1 // indirect
+	github.com/containerd/continuity v0.4.2 // indirect
 	github.com/containerd/stargz-snapshotter/estargz v0.15.1 // indirect
 	github.com/cosmos/btcutil v1.0.5 // indirect
 	github.com/cosmos/go-bip39 v1.0.0 // indirect
@@ -263,7 +264,7 @@ require (
 	github.com/vbatts/tar-split v0.11.5 // indirect
 	github.com/zondax/hid v0.9.2 // indirect
 	github.com/zondax/ledger-go v0.14.3 // indirect
-	go.etcd.io/bbolt v1.3.8 // indirect
+	go.etcd.io/bbolt v1.3.10 // indirect
 	go.opencensus.io v0.24.0 // indirect
 	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.49.0 // indirect
 	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.53.0 // indirect

go.sum

@@ -364,8 +364,8 @@ github.com/cometbft/cometbft v0.38.7 h1:ULhIOJ9+LgSy6nLekhq9ae3juX3NnQUMMPyVdhZV
 github.com/cometbft/cometbft v0.38.7/go.mod h1:HIyf811dFMI73IE0F7RrnY/Fr+d1+HuJAgtkEpQjCMY=
 github.com/cometbft/cometbft-db v0.9.1 h1:MIhVX5ja5bXNHF8EYrThkG9F7r9kSfv8BX4LWaxWJ4M=
 github.com/cometbft/cometbft-db v0.9.1/go.mod h1:iliyWaoV0mRwBJoizElCwwRA9Tf7jZJOURcRZF9m60U=
-github.com/containerd/continuity v0.3.0 h1:nisirsYROK15TAMVukJOUyGJjz4BNQJBVsNvAXZJ/eg=
-github.com/containerd/continuity v0.3.0/go.mod h1:wJEAIwKOm/pBZuBd0JmeTvnLquTB1Ag8espWhkykbPM=
+github.com/containerd/continuity v0.4.2 h1:v3y/4Yz5jwnvqPKJJ+7Wf93fyWoCB3F5EclWG023MDM=
+github.com/containerd/continuity v0.4.2/go.mod h1:F6PTNCKepoxEaXLQp3wDAjygEnImnZ/7o4JzpodfroQ=
 github.com/containerd/log v0.1.0 h1:TCJt7ioM2cr/tfR8GPbGf9/VRAX8D2B4PjzCpfX540I=
 github.com/containerd/log v0.1.0/go.mod h1:VRRf09a7mHDIRezVKTRCrOq78v577GXq3bSa3EhrzVo=
 github.com/containerd/stargz-snapshotter/estargz v0.15.1 h1:eXJjw9RbkLFgioVaTG+G/ZW/0kEe2oEKCdS/ZxIyoCU=
@@ -1160,8 +1160,8 @@ github.com/zondax/hid v0.9.2/go.mod h1:l5wttcP0jwtdLjqjMMWFVEE7d1zO0jvSPA9OPZxWp
 github.com/zondax/ledger-go v0.14.3 h1:wEpJt2CEcBJ428md/5MgSLsXLBos98sBOyxNmCjfUCw=
 github.com/zondax/ledger-go v0.14.3/go.mod h1:IKKaoxupuB43g4NxeQmbLXv7T9AlQyie1UpHb342ycI=
 go.etcd.io/bbolt v1.3.3/go.mod h1:IbVyRI1SCnLcuJnV2u8VeU0CEYM7e686BmAb1XKL+uU=
-go.etcd.io/bbolt v1.3.8 h1:xs88BrvEv273UsB79e0hcVrlUWmS0a8upikMFhSyAtA=
-go.etcd.io/bbolt v1.3.8/go.mod h1:N9Mkw9X8x5fupy0IKsmuqVtoGDyxsaDlbk4Rd05IAQw=
+go.etcd.io/bbolt v1.3.10 h1:+BqfJTcCzTItrop8mq/lbzL8wSGtj94UO/3U31shqG0=
+go.etcd.io/bbolt v1.3.10/go.mod h1:bK3UQLPJZly7IlNmV7uVHJDxfe5aK9Ll93e/74Y9oEQ=
 go.etcd.io/etcd v0.0.0-20191023171146-3cf2f69b5738/go.mod h1:dnLIgRNXwCJa5e+c6mIZCrds/GIG4ncV9HhK5PX7jPg=
 go.opencensus.io v0.20.1/go.mod h1:6WKK9ahsWS3RSO+PY9ZHZUfv2irvY6gN279GOPZjmmk=
 go.opencensus.io v0.20.2/go.mod h1:6WKK9ahsWS3RSO+PY9ZHZUfv2irvY6gN279GOPZjmmk=

testutil/keeper/supplier.go

@@ -89,6 +89,3 @@ func SupplierKeeper(t testing.TB) (keeper.Keeper, context.Context) {
 
 	return k, ctx
 }
-
-// TODO_OPTIMIZE: Index suppliers by service so we can easily query k.GetAllSuppliers(ctx, Service)
-// func (k Keeper) GetAllSuppliers(ctx, sdkContext, serviceId string) (suppliers []sharedtypes.Supplier) {}

testutil/keeper/tokenomics.go

@@ -144,6 +144,15 @@ func TokenomicsKeeperWithActorAddrs(t testing.TB, service *sharedtypes.Service)
 		SetApplication(gomock.Any(), gomock.Any()).
 		AnyTimes()
 
+	// Mock the supplier keeper.
+	mockSupplierKeeper := mocks.NewMockSupplierKeeper(ctrl)
+
+	// Get test supplier if the address matches.
+	mockSupplierKeeper.EXPECT().
+		GetSupplier(gomock.Any(), gomock.Eq(supplier.Address)).
+		Return(supplier, true).
+		AnyTimes()
+
 	// Mock the bank keeper.
 	mockBankKeeper := mocks.NewMockBankKeeper(ctrl)
 	mockBankKeeper.EXPECT().
@@ -179,6 +188,7 @@ func TokenomicsKeeperWithActorAddrs(t testing.TB, service *sharedtypes.Service)
 		mockBankKeeper,
 		mockAccountKeeper,
 		mockApplicationKeeper,
+		mockSupplierKeeper,
 		mockProofKeeper,
 		mockSharedKeeper,
 		mockSessionKeeper,
@@ -359,6 +369,7 @@ func NewTokenomicsModuleKeepers(
 		bankKeeper,
 		accountKeeper,
 		appKeeper,
+		supplierKeeper,
 		proofKeeper,
 		sharedKeeper,
 		sessionKeeper,

x/supplier/keeper/supplier.go

@@ -62,5 +62,5 @@ func (k Keeper) GetAllSuppliers(ctx context.Context) (suppliers []sharedtypes.Su
 	return
 }
 
-// TODO_MAINNET: Index suppliers by service so we can easily query k.GetAllSuppliers(ctx, Service)
+// TODO_OPTIMIZE: Index suppliers by service so we can easily query k.GetAllSuppliers(ctx, Service)
 // func (k Keeper) GetAllSuppliers(ctx, sdkContext, serviceId string) (suppliers []sharedtypes.Supplier) {}

x/tokenomics/keeper/keeper.go

@@ -26,6 +26,7 @@ type Keeper struct {
 	bankKeeper        types.BankKeeper
 	accountKeeper     types.AccountKeeper
 	applicationKeeper types.ApplicationKeeper
+	supplierKeeper    types.SupplierKeeper
 	proofKeeper       types.ProofKeeper
 	sharedKeeper      types.SharedKeeper
 	sessionKeeper     types.SessionKeeper
@@ -42,6 +43,7 @@ func NewKeeper(
 	bankKeeper types.BankKeeper,
 	accountKeeper types.AccountKeeper,
 	applicationKeeper types.ApplicationKeeper,
+	supplierKeeper types.SupplierKeeper,
 	proofKeeper types.ProofKeeper,
 	sharedKeeper types.SharedKeeper,
 	sessionKeeper types.SessionKeeper,
@@ -61,6 +63,7 @@ func NewKeeper(
 		bankKeeper:        bankKeeper,
 		accountKeeper:     accountKeeper,
 		applicationKeeper: applicationKeeper,
+		supplierKeeper:    supplierKeeper,
 		proofKeeper:       proofKeeper,
 		sharedKeeper:      sharedKeeper,
 		sessionKeeper:     sessionKeeper,

x/tokenomics/keeper/settle_session_accounting.go

@@ -6,16 +6,13 @@ import (
 
 	"cosmossdk.io/math"
 	cosmostypes "github.com/cosmos/cosmos-sdk/types"
+	"github.com/pokt-network/smt"
 
 	"github.com/pokt-network/poktroll/app/volatile"
 	"github.com/pokt-network/poktroll/pkg/crypto/protocol"
-
-	"github.com/pokt-network/smt"
-
 	"github.com/pokt-network/poktroll/telemetry"
 	apptypes "github.com/pokt-network/poktroll/x/application/types"
 	prooftypes "github.com/pokt-network/poktroll/x/proof/types"
-	suppliertypes "github.com/pokt-network/poktroll/x/supplier/types"
 	tokenomicstypes "github.com/pokt-network/poktroll/x/tokenomics/types"
 )
 
@@ -33,9 +30,11 @@ func (k Keeper) SettleSessionAccounting(
 ) (err error) {
 	logger := k.Logger().With("method", "SettleSessionAccounting")
 
+	// Declaring variables that will be emitted by telemetry
 	settlementCoin := cosmostypes.NewCoin("upokt", math.NewInt(0))
 	isSuccessful := false
-	// This is emitted only when the function returns.
+
+	// This is emitted only when the function returns (successful or not)
 	defer telemetry.EventSuccessCounter(
 		"settle_session_accounting",
 		func() float32 {
@@ -47,7 +46,7 @@ func (k Keeper) SettleSessionAccounting(
 		func() bool { return isSuccessful },
 	)
 
-	// Make sure the claim is not nil
+	// Ensure the claim is not nil
 	if claim == nil {
 		logger.Error("received a nil claim")
 		return tokenomicstypes.ErrTokenomicsClaimNil
@@ -64,26 +63,30 @@ func (k Keeper) SettleSessionAccounting(
 		return tokenomicstypes.ErrTokenomicsSessionHeaderInvalid
 	}
 
+	// Retrieve the supplier address that will be getting rewarded; providing services
 	supplierAddr, err := cosmostypes.AccAddressFromBech32(claim.GetSupplierAddress())
 	if err != nil || supplierAddr == nil {
 		return tokenomicstypes.ErrTokenomicsSupplierAddressInvalid
 	}
 
+	// Retrieve the application address that is being charged; getting services
 	applicationAddress, err := cosmostypes.AccAddressFromBech32(sessionHeader.GetApplicationAddress())
 	if err != nil || applicationAddress == nil {
 		return tokenomicstypes.ErrTokenomicsApplicationAddressInvalid
 	}
 
-	// Retrieve the sum of the root as a proxy into the amount of work done
+	// Retrieve the root of the claim to determine the amount of work done
 	root := (smt.MerkleSumRoot)(claim.GetRootHash())
 
+	// Ensure the root hash is valid
 	if !root.HasDigestSize(protocol.TrieHasherSize) {
 		return tokenomicstypes.ErrTokenomicsRootHashInvalid.Wrapf(
 			"root hash has invalid digest size (%d), expected (%d)",
 			root.DigestSize(), protocol.TrieHasherSize,
 		)
 	}
 
+	// Retrieve the sum of the root hash to determine the amount of work (compute units) done
 	claimComputeUnits, err := root.Sum()
 	if err != nil {
 		return tokenomicstypes.ErrTokenomicsRootHashInvalid.Wrapf("%v", err)
@@ -96,129 +99,72 @@ func (k Keeper) SettleSessionAccounting(
 		"supplier", supplierAddr,
 		"application", applicationAddress,
 	)
-
 	logger.Info("About to start session settlement accounting")
 
-	// Retrieve the staked application record
+	// Retrieve the on-chain staked application record
 	application, foundApplication := k.applicationKeeper.GetApplication(ctx, applicationAddress.String())
 	if !foundApplication {
 		logger.Warn(fmt.Sprintf("application for claim with address %q not found", applicationAddress))
 		return tokenomicstypes.ErrTokenomicsApplicationNotFound
 	}
 
+	// Retrieve the on-chain staked application record
+	supplier, foundSupplier := k.supplierKeeper.GetSupplier(ctx, supplierAddr.String())
+	if !foundSupplier {
+		logger.Warn(fmt.Sprintf("supplier for claim with address %q not found", supplierAddr))
+		return tokenomicstypes.ErrTokenomicsSupplierNotFound
+	}
+
+	// Determine the total number of tokens that'll be used for settling the session.
+	// When the network achieves equilibrium, this will be the mint & burn.
+	// TODO_IN_THIS_PR: Simplify: this function should just take in a ServiceId and the one below should take in the root
 	computeUnitsPerRelay, err := k.getComputUnitsPerRelayFromApplication(application, sessionHeader.Service.Id)
 	if err != nil {
 		return err
 	}
-
 	computeUnitsToTokensMultiplier := k.GetParams(ctx).ComputeUnitsToTokensMultiplier
-
-	logger.Info(fmt.Sprintf("About to start settling claim for %d compute units with CUPR %d and CUTTM %d", claimComputeUnits, computeUnitsPerRelay, computeUnitsToTokensMultiplier))
-
-	// Calculate the amount of tokens to mint & burn
 	settlementCoin, err = relayCountToCoin(claimComputeUnits, computeUnitsPerRelay, computeUnitsToTokensMultiplier)
 	if err != nil {
 		return err
 	}
 
-	settlementCoins := cosmostypes.NewCoins(settlementCoin)
-
+	// Start claiming log line!
 	logger.Info(fmt.Sprintf(
-		"%d compute units equate to %s for session %s",
+		"About to start claiming (%d) compute units equate to (%s) coins for session (%s) with ComputeUnitsPerRelay (%d) and ComputeUnitsToTokenMultiplier (%d)",
 		claimComputeUnits,
 		settlementCoin,
 		sessionHeader.SessionId,
+		computeUnitsPerRelay,
+		computeUnitsToTokensMultiplier,
 	))
 
-	// NB: We are doing a mint & burn + transfer, instead of a simple transfer
-	// of funds from the supplier to the application in order to enable second
-	// order economic effects with more optionality. This could include funds
-	// going to pnf, delegators, enabling bonuses/rebates, etc...
-
-	// Mint new uPOKT to the supplier module account.
-	// These funds will be transferred to the supplier below.
-	if err = k.bankKeeper.MintCoins(
-		ctx, suppliertypes.ModuleName, settlementCoins,
-	); err != nil {
-		return tokenomicstypes.ErrTokenomicsSupplierModuleMintFailed.Wrapf(
-			"minting %s to the supplier module account: %v",
-			settlementCoin,
-			err,
-		)
-	}
-	logger.Info(fmt.Sprintf("minted %s in the supplier module", settlementCoin))
-
-	// Send the newley minted uPOKT from the supplier module account
-	// to the supplier's account.
-	if err = k.bankKeeper.SendCoinsFromModuleToAccount(
-		ctx, suppliertypes.ModuleName, supplierAddr, settlementCoins,
-	); err != nil {
-		return tokenomicstypes.ErrTokenomicsSupplierModuleMintFailed.Wrapf(
-			"sending %s to supplier with address %s: %v",
-			settlementCoin,
-			supplierAddr,
-			err,
-		)
-	}
-	logger.Info(fmt.Sprintf("sent %s from the supplier module to the supplier account with address %q", settlementCoin, supplierAddr))
-
-	// Verify that the application has enough uPOKT to pay for the services it consumed
-	if application.GetStake().IsLT(settlementCoin) {
-		logger.Warn(fmt.Sprintf(
-			"THIS SHOULD NEVER HAPPEN. Application with address %s needs to be charged more than it has staked: %v > %v",
-			applicationAddress,
-			settlementCoins,
-			application.Stake,
-		))
-		// TODO_MAINNET(@Olshansk, @RawthiL): The application was over-serviced in the last session so it basically
-		// goes "into debt". Need to design a way to handle this when we implement
-		// probabilistic proofs and add all the parameter logic. Do we touch the application balance?
-		// Do we just let it go into debt? Do we penalize the application? Do we unstake it? Etc...
-		expectedBurn := settlementCoin
-		// Make the settlement amount the maximum stake that the application has remaining.
-		settlementCoin = *application.GetStake()
-		settlementCoins = cosmostypes.NewCoins(settlementCoin)
-
-		applicationOverservicedEvent := &tokenomicstypes.EventApplicationOverserviced{
-			ApplicationAddr: applicationAddress.String(),
-			ExpectedBurn:    &expectedBurn,
-			EffectiveBurn:   application.GetStake(),
-		}
-
-		eventManager := cosmostypes.UnwrapSDKContext(ctx).EventManager()
-		if err = eventManager.EmitTypedEvent(applicationOverservicedEvent); err != nil {
-			return tokenomicstypes.ErrTokenomicsApplicationOverserviced.Wrapf(
-				"application address: %s; expected burn %s; effective burn: %s",
-				application.GetAddress(),
-				expectedBurn.String(),
-				application.GetStake().String(),
-			)
-		}
-	}
-
-	// Burn uPOKT from the application module account which was held in escrow
-	// on behalf of the application account.
-	if err = k.bankKeeper.BurnCoins(
-		ctx, apptypes.ModuleName, settlementCoins,
+	//
+	if err := k.ProcessTokenLogicModules(
+		ctx,
+		claim.SessionHeader,
+		&application,
+		&supplier,
+		settlementCoin,
 	); err != nil {
-		return tokenomicstypes.ErrTokenomicsApplicationModuleBurn.Wrapf("burning %s from the application module account: %v", settlementCoin, err)
+		logger.Warn(fmt.Sprintf("failed to trigger the token-logic-module settle session accounting for supplier %s", supplierAddr))
+		return err
 	}
-	logger.Info(fmt.Sprintf("burned %s from the application module account", settlementCoin))
 
-	// Update the application's on-chain stake
-	newAppStake, err := application.Stake.SafeSub(settlementCoin)
-	if err != nil {
-		return tokenomicstypes.ErrTokenomicsApplicationNewStakeInvalid.Wrapf("application %q stake cannot be reduced to a negative amount %v", applicationAddress, newAppStake)
-	}
-	application.Stake = &newAppStake
+	// Update the application's on-chain record
 	k.applicationKeeper.SetApplication(ctx, application)
-	logger.Info(fmt.Sprintf("updated stake for application with address %q to %s", applicationAddress, newAppStake))
+	logger.Info(fmt.Sprintf("updated on-chain application record with address %q", applicationAddress))
+
+	// Update the application's on-chain record
+	k.supplierKeeper.SetSupplier(ctx, supplier)
+	logger.Info(fmt.Sprintf("updated on-chain supplier record with address %q", supplierAddr))
 
+	// Update isSuccessful to true for telemetry
 	isSuccessful = true
 	return nil
 }
 
 // relayCountToCoin calculates the amount of uPOKT to mint based on the number of relays, the service-specific ComputeUnitsPerRelay, and the ComputeUnitsPerTokenMultiplier tokenomics param
+// TODO_IN_THIS_PR: What if we use root smt.MerkleRoot instead?
 func relayCountToCoin(numRelays, computeUnitsPerRelay uint64, computeUnitsToTokensMultiplier uint64) (cosmostypes.Coin, error) {
 	upokt := math.NewInt(int64(numRelays * computeUnitsPerRelay * computeUnitsToTokensMultiplier))