[Tokenomics] Settlement safety

[bryanchriswhite]

Objective

Improve saftey in claim settlement code.

Status

• [Tokenomics] Harden settlement (part 1: TLM isolation) #889
• [Code Health] Harden settlement (part 2: (non-)halting settlement error alignment) #904

See: Unhaltable settlement notion doc

Origin Document

Discussion with @red-0ne based on recent observations: Claim Settlement Safety - notion doc.

Proposal Draft

type TLMMintBurn struct {
	TLMName string
	DestinationAddr string
	Coin *cosmostypes.Coin
}

type TLMTransfer struct {
	TLMName string
	SourceAddr: string
	DestinationAddr: string	
	Coin *cosmostypes.Coin
}

type TLMProcessingResult { // Supersedes PendingClaimResult
	Claims: []*sharedtypes.Claim
	Mints: []TLMMintBurn
	Burns: []TLMMintBurn
	Transfers: []TLMTransfer
}

func (tlmPR) GetNumComputeUnits() int64
func (tlmPR) GetNumRelays() int64
func (tlmPR) GetNumClaims() int64
func (tlmPR) GetApplicationAddrs() []string
func (tlmPR) GetSupplierAddrs() []string
func (tlmPR) GetSessionEndHeight() int64
func (tlmPR) GetServices() []string // use for determinstic loops
func (tlmPR) RelaysPerServiceMap() map[string]uint64 // SHOULD NEVER be used for loops

func (tlmPR) Append(TLMProcessingResult) TLMProcessingResult

var tokenLogicModuleProcessors = []TokenLogicModule{...}

type TokenLogicModule struct {
	Name string
	Process func(
		context.Context,
		*sharedtypes.Service,
		*sessiontypes.SessionHeader,
		*apptypes.Application,
		*sharedtypes.Supplier,
		cosmostypes.Coin, // This is the "actualSettlementCoin" rather than just the "claimCoin" because of how settlement functions; see ensureClaimAmountLimits for details.
		*servicetypes.RelayMiningDifficulty,
	) (TLMProcessingResult, error)
}

Goals

• Harden claim settlement business logic against chain halt vectors
  • Isolate ALL TLM logic from keepers and the multistore
  • Mutate the state once, after TLM processing
  • Continue processing other claims if there is an error processing a particular claim
    • Emit an error event
  • Remove map type data structures from claim settlement business logic
• Improve the TLM processing foundation
  • Redefine TLMs as objects

Deliverables

• A PR which implements TLMProcessingResult, TokenLogicModule, and dependencies.
• A PR which refactors each TLM method to be a static TokenLogicModule in its own file and tokenLogicModuleProcessorMap map as a []TokenLogicModule slice.

Non-goals / Non-deliverables

• Implementing or refactoring any TLM business logic.

General deliverables

• Comments: Add/update TODOs and comments alongside the source code so it is easier to follow.
• Testing: Add new tests (unit and/or E2E) to the test suite.
• Makefile: Add new targets to the Makefile to make the new functionality easier to use.
• Documentation: Update architectural or development READMEs; use mermaid diagrams where appropriate.

---

Creator: @bryanchriswhite
Co-Owners: @red-0ne

[Olshansk]

@bryanchriswhite Leaving feedback on the notion doc here.

Using a map REQUIRES that all TLM functions are commutative. While it is probably a great requirement or goal, it doesn’t mean that we need to make a design choice which makes it a hard constraint, thereby introducing a chain halt pathway.

@bryanchriswhite I want us to keep this requirement.

• Keeps TLMs independent of one another
• Makes it easier to ensure lack of dependency (execution results) from one on another
• Reduces risk of adding/removing them in the future
• Enables experimantion easier

Isolate TLM logic from keepers

👍 if possible.

Mutate all state deterministically, after TLM processing/calculations

👍 if possible

Ensure a single unexpected claim error doesn’t halt claim processing

Makes sense.

TLMName string

Can you make this an iota (enum)

type TLMProcessingResult { // Supersedes PendingClaimResult
	Claims: []*sharedtypes.Claim
	Mints: []TLMMintBurn
	Burns: []TLMMintBurn
	Transfers: []TLMTransfer
}

I'm not a fan of parallel arrays and would rather do something like this:

// Supersedes PendingClaimResult
type TLMProcessingResult struct { 
	Claim *sharedtypes.Claim
	Mints []TLMMintBurn
	Burns []TLMMintBurn
	Transfers []TLMTransfer
}

type TLMProcessingResults struct {
	TLMResults []*TLMProcessingResult
}

Other asks, ensure:

1. Sufficient error/warning/info logging + events along the way
2. Ensure (1) for each individual result
3. Would love to be able to do a simple SQL query of (2) when the time is right

[bryanchriswhite]

Using a map REQUIRES that all TLM functions are commutative. While it is probably a great requirement or goal, it doesn’t mean that we need to make a design choice which makes it a hard constraint, thereby introducing a chain halt pathway.

@bryanchriswhite I want us to keep this requirement.

• Keeps TLMs independent of one another
• Makes it easier to ensure lack of dependency (execution results) from one on another
• Reduces risk of adding/removing them in the future
• Enables experimantion easier

No argument here. My point was just that there's no need to aim a footgun at ourselves by using a map.

TLMName string

Can you make this an iota (enum)

👍

I'm not a fan of parallel arrays and would rather do something like this:

// Supersedes PendingClaimResult
type TLMProcessingResult struct { 
	Claim *sharedtypes.Claim
	Mints []TLMMintBurn
	Burns []TLMMintBurn
	Transfers []TLMTransfer
}

type TLMProcessingResults struct {
	TLMResults []*TLMProcessingResult
}

Good point, agreed. 👍

1. Sufficient error/warning/info logging + events along the way

👍

2. Ensure (1) for each individual result
3. Would love to be able to do a simple SQL query of (2) when the time is right

@Olshansk, can you elaborate on these, I'm not sure what's being referenced or asked.

[Olshansk]

Ensure (1) for each individual result

Request that for each successful / failed claim, there is sufficient (use your best judgment) error/warning/info logging + events along the way.

Would love to be able to do a simple SQL query of (2) when the time is right

Once these events are indexed in pocketdex, adding a few examples like this would go a long way:

• Query all successful claims
• Query all failed claims
• Query all mints
• Query all burns
• Etc....