RFC: Extensible Multi-Level Halt System

[notJoon]

1. Overview

This RFC proposes enhancing current halt system with an extensible architecture. This enhancement will enable flexible addition and management of various halt policies.

2. Motivation

• Need for flexible halt policies to respond to various real-world conditions
• Extensiblity requirement for halt policies as new features are added
• Systematic halt policy management and improved testability
• Need for fine-grained control mechanisms to protect user assets

3. Design Principles

• Easy-to-Extent: Both single and composite policies can be easily added, modified, and extended.
• Type safety guarantees: Ensure reliable policy evaluation through a strongly typed system.
• Functional Style: By adopting a functional style, the policy evaluation logic is clear and easy-to-test.
• Composite Policy Support: Multiple halt policies can be combined through logical operators such as AND/OR. (Optional)

4. Technical Specification

4.1 Core Interface

Operation Interface

The Operation interface defines the contract for protocol operations that can be subject to halt conditions. It provides a standardized way to identify and describe different types of operations in the system.

type Operation interface {
    Type() OperationType
    Name() string
    Description() string
}

Halt-Level Interface

The HaltLevel interface defines the contract for different halt states in the system. It encapsulates the logic for determining which operations are allowed under specific halt conditions.

type HaltLevel interface {
    Level() uint8                          // Returns the numeric level of the halt state
    Name() string                          // Returns a human-readable name for the halt level
    Description() string                   // Provides a detailed description of the halt level
    IsOperationAllowed(Operation) bool     // Determines if a given operation is permitted at this halt level
}

4.2 Base Implementations

Basic Operation

BasicOperation provides a standard implementation of the Operation interface. It serves as a base structure for defining protocol operations.

type BasicOperation struct {
    opType      OperationType
    name        string
    description string
}

Basic Halt-Level

BasicHaltLevel provides a standard implementation of the HaltLevel interface. It implements a simple permission-based system using a map of allowed operations.

type BasicHaltLevel struct {
    level       uint8
    name        string
    description string
    allowedOps  map[OperationType]bool
}

Compoisite Halt-Level

This item is optional.

Support for combining multiple halt policies. by setting and AND or OR value in the operator field to determine whether all or only one of the child policies should be allowed.

type CompositeHaltLevel struct {
    name        string
    description string
    levels      []HaltLevel
    operator    string // "AND" | "OR"
}

Halt Manager

The HaltManager is the central component that coordinates the halt system. It maintains the current halt state and manages the registration and lookup of operations and halt levels.

type HaltManager struct {
    currentLevel HaltLevel
    levels       map[uint8]HaltLevel
    operations   map[OperationType]Operation
}

Key responsibilities of the HaltManager include:

• Maintainging the current halt state
• Managing operation and halt level registrations
• Enforcing halt level transitions
• Providing a centralized point for halt-related queries

5. Usage Example

5.1 Basic Usage

// Usage in Mint function
func Mint(...) {
    common.AssertOperation(OpTypeLiquidity)
    // ...
}

// Usage in Swap function
func Swap(...) {
    common.AssertOperation(OpTypeSwap)
    // ...
}

5.2 Adding New Operation

// Define new operation type
const OpTypeNewFeature OperationType = "someFeature"

// Register operation
manager.RegisterOperation(NewOperation(
    OpTypeNewFeature,
    "NewFeature",
    "new feature operations"
))

5.3 Adding New Halt-Levels

// Define and register new halt level
manager.RegisterHaltLevel(NewHaltLevel(
    4, // level
    "NewFeatureHalt",
    "New features disabled, other operations allowed",
    map[OperationType]bool{
        OpTypeSwap:      true,
        OpTypeLiquidity: true,
        OpTypeWithdraw:  true,
        OpTypeNewFeature: false,
    }
))

5.4 Implementing Custom Halt Policies

// Time-based Halt Level implementation example
type TimeBasedHaltLevel struct {
    BasicHaltLevel
    startTime int64
    endTime   int64
}

func (t TimeBasedHaltLevel) IsOperationAllowed(op Operation) bool {
    currentTime := std.GetHeight() // or appropriate time retrieval method
    if currentTime < t.startTime || currentTime > t.endTime {
        return t.BasicHaltLevel.IsOperationAllowed(op)
    }
    return false
}

// Usage example
manager.RegisterHaltLevel(NewTimeBasedHaltLevel(
    5,
    "MaintenanceHalt",
    "Scheduled maintenance period",
    map[OperationType]bool{...},
    startTime,
    endTime,
))

6. Default Halt-Levels

Level	Name	Description	Restrictions
0	NoHalt	Normal Operation	None
1	SwapHalt	Swap operations halted	No swaps
2	LiquidityHalt	Liquidity operations halted	No swaps, no liquidity operations
3	EmergencyHalt	Emergency Situation	Only withdrawals allowed
4	CompleteHalt	Complete shutdown	All operations disabled

7. Security Considerations

7.1 Access Control

• Admin/Governance permission validation
• Prevent unauthorized access

7.2 State Change Control

• Prevent inappropriate state transitions
• Validation procedures for state changes
• Emergency response procedures

8. Open Questions

1. State Transition Rules:
   • Whether the current transition rules that only allow one step are sufficient,
     or if additional transition constraints are needed (e.g., logging, limiting the time interval between transitions).
2. Event Logging Enhancements:
   • Is there a need to enhance auditing by including additional metadata such as state transitions, timestamps, transaction IDs, etc.