feat: add configurable sanction durations (#490)

## Summary

- Add `SanctionConfig` to allow operators to configure endpoint sanction
timing
- `session_sanction_duration`: How long session sanctions last (default:
1h)
- `cache_cleanup_interval`: How often expired sanctions are purged
(default: 10m)
- Enables tuning based on network conditions

## Changes

| File | Description |
|------|-------------|
| `protocol/shannon/config.go` | Add `SanctionConfig` struct with
`HydrateDefaults()` |
| `protocol/shannon/sanctioned_endpoints_store.go` | Use config values
instead of hardcoded defaults |
| `protocol/shannon/protocol.go` | Pass config to store constructors |
| `protocol/shannon/sanctioned_endpoints_store_test.go` | Tests
verifying sanctions expire after configured duration |
| `docusaurus/docs/develop/configs/2_gateway_config.md` | Documentation
for new config |
| `config/examples/config.shannon_example.yaml` | Example configuration
|
| `config/config.schema.yaml` | Schema validation |

## Example Configuration

```yaml
shannon_config:
  gateway_config:
    sanction_config:
      session_sanction_duration: 30m  # Default: 1h
      cache_cleanup_interval: 5m       # Default: 10m
```

## Test plan

- [x] Unit tests pass (`go test ./protocol/shannon/...`)
- [x] New tests verify sanctions expire after configured duration
- [x] Full build passes (`go build ./...`)
- [x] Lint passes (`make go_lint`)
- [x] E2E tests pass (`make e2e_test eth`)

Author: jorgecuesta

cmd/main.go

@@ -64,8 +64,12 @@ func main() {
 	// Log the config path
 	logger.Info().Msgf("Starting PATH using config file: %s", configPath)
 
+	// Create a context for background services (pprof, hydrator, reputation) that can be canceled during shutdown.
+	// This context is used to signal graceful shutdown to all background goroutines.
+	backgroundCtx, backgroundCancel := context.WithCancel(context.Background())
+
 	// Create Shannon protocol instance (now the only supported protocol)
-	protocol, err := getShannonProtocol(logger, config.GetGatewayConfig())
+	protocol, err := getShannonProtocol(backgroundCtx, logger, config.GetGatewayConfig())
 	if err != nil {
 		log.Fatalf(`{"level":"fatal","error":"%v","message":"failed to create protocol"}`, err)
 	}
@@ -82,10 +86,6 @@ func main() {
 		log.Fatalf(`{"level":"fatal","error":"%v","message":"failed to start metrics server"}`, err)
 	}
 
-	// Create a context for background services (pprof, hydrator) that can be canceled during shutdown.
-	// This context is used to signal graceful shutdown to all background goroutines.
-	backgroundCtx, backgroundCancel := context.WithCancel(context.Background())
-
 	// Setup the pprof server with the background context for graceful shutdown
 	setupPprofServer(backgroundCtx, logger, pprofAddr)
 

cmd/shannon.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"context"
 	"fmt"
 
 	"github.com/pokt-network/poktroll/pkg/polylog"
@@ -36,15 +37,15 @@ func getShannonFullNode(logger polylog.Logger, config *shannonconfig.ShannonGate
 }
 
 // getShannonProtocol returns an instance of the Shannon protocol using the supplied Shannon-specific configuration.
-func getShannonProtocol(logger polylog.Logger, config *shannonconfig.ShannonGatewayConfig) (gateway.Protocol, error) {
+func getShannonProtocol(ctx context.Context, logger polylog.Logger, config *shannonconfig.ShannonGatewayConfig) (gateway.Protocol, error) {
 	logger.Info().Msg("Starting PATH gateway with Shannon protocol")
 
 	fullNode, err := getShannonFullNode(logger, config)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create a Shannon full node instance: %w", err)
 	}
 
-	protocol, err := shannon.NewProtocol(logger, config.GatewayConfig, fullNode)
+	protocol, err := shannon.NewProtocol(ctx, logger, config.GatewayConfig, fullNode)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create a Shannon protocol instance: %w", err)
 	}

config/config.schema.yaml

@@ -149,6 +149,19 @@ properties:
                   description: "Whether to send all traffic to fallback endpoints for this service, regardless of protocol endpoint health."
                   type: boolean
                   default: false
+          sanction_config:
+            description: "Configuration for the endpoint sanction system. Controls how long misbehaving endpoints are excluded from selection."
+            type: object
+            additionalProperties: false
+            properties:
+              session_sanction_duration:
+                description: "Duration that session-based sanctions remain active. Endpoints with session sanctions will be excluded from selection for this duration. Format: Go duration string (e.g., '30m', '1h', '2h'). Default: 1h"
+                type: string
+                pattern: "^[0-9]+[smh]$"
+              cache_cleanup_interval:
+                description: "Interval for purging expired sanction entries from the cache. Format: Go duration string (e.g., '5m', '10m'). Default: 10m"
+                type: string
+                pattern: "^[0-9]+[smh]$"
   # Logger Configuration (optional)
   logger_config:
     description: "Optional configuration for the logger. If not specified, info level will be used."

config/config_test.go

@@ -11,6 +11,7 @@ import (
 	"github.com/pokt-network/path/network/grpc"
 	"github.com/pokt-network/path/protocol"
 	shannonprotocol "github.com/pokt-network/path/protocol/shannon"
+	"github.com/pokt-network/path/reputation"
 )
 
 // getTestDefaultGRPCConfig returns a GRPCConfig with default values applied
@@ -82,6 +83,17 @@ func Test_LoadGatewayConfigFromYAML(t *testing.T) {
 								},
 							},
 						},
+						SanctionConfig: shannonprotocol.SanctionConfig{
+							SessionSanctionDuration: 30 * time.Minute,
+							CacheCleanupInterval:    5 * time.Minute,
+						},
+						ReputationConfig: reputation.Config{
+							Enabled:         true,
+							StorageType:     "memory",
+							InitialScore:    80,
+							MinThreshold:    30,
+							RecoveryTimeout: 5 * time.Minute,
+						},
 					},
 				},
 				Router: RouterConfig{

config/examples/config.shannon_example.yaml

@@ -74,6 +74,48 @@ shannon_config:
         # only `default_url` is specified and the other RPC type URLs are omitted.
         - default_url: "https://eth.rpc.backup.io"
 
+    # Optional sanction configuration
+    # Controls how long misbehaving endpoints are excluded from selection
+    sanction_config:
+      # How long session-based sanctions last before the endpoint can be selected again
+      # Default: 1h (1 hour)
+      session_sanction_duration: 30m
+      # How often expired sanctions are cleaned up from memory
+      # Default: 10m (10 minutes)
+      cache_cleanup_interval: 5m
+
+    # Optional reputation configuration
+    # Provides gradual endpoint scoring based on reliability patterns
+    # Works in addition to binary sanctions, not as a replacement
+    reputation_config:
+      # Enable/disable the reputation system
+      # Default: false (only binary sanctions are used)
+      enabled: true
+      # Storage backend for reputation data
+      # Options: "memory" (single instance) or "redis" (multi-instance deployments)
+      # Default: "memory"
+      storage_type: "memory"
+      # Starting score for new endpoints (0-100 scale)
+      # Default: 80
+      initial_score: 80
+      # Minimum score required for endpoint selection
+      # Endpoints below this threshold are filtered out
+      # Default: 30
+      min_threshold: 30
+      # Time after which inactive endpoint scores can be re-evaluated
+      # Default: 5m
+      recovery_timeout: 5m
+      # Redis configuration (only used when storage_type is "redis")
+      # redis:
+      #   address: "localhost:6379"
+      #   password: ""
+      #   db: 0
+      #   key_prefix: "path:reputation:"
+      #   pool_size: 10
+      #   dial_timeout: 5s
+      #   read_timeout: 3s
+      #   write_timeout: 3s
+
 # Optional logger configuration
 logger_config:
   # Valid values are: debug, info, warn, error

docusaurus/docs/develop/configs/2_gateway_config.md

@@ -46,6 +46,13 @@ shannon_config:
         fallback_urls:
           - "https://eth.rpc.grove.city/v1/1a2b3c4d"
           - "https://eth.rpc.grove.city/v1/5e6f7a8b"
+    # (Optional) Endpoint reputation system
+    reputation_config:
+      enabled: true
+      storage_type: "memory"
+      initial_score: 80
+      min_threshold: 30
+      recovery_timeout: "5m"
 
 # (Optional) Logger Configuration
 logger_config:
@@ -146,6 +153,8 @@ shannon_config:
 | `gateway_private_key_hex`     | string   | Yes                      | -       | 64-character hex-encoded `secp256k1` gateway private key              |
 | `owned_apps_private_keys_hex` | string[] | Only in centralized mode | -       | List of 64-character hex-encoded `secp256k1` application private keys |
 | `service_fallback`            | array    | No                       | -       | Array of service fallback configurations (see below for details)      |
+| `sanction_config`             | object   | No                       | -       | Configuration for endpoint sanction system (see below for details)    |
+| `reputation_config`           | object   | No                       | -       | Configuration for endpoint reputation system (see below for details)  |
 
 **`service_fallback` (optional)**
 
@@ -181,6 +190,94 @@ TODO_DOCUMENT(@adshmh): Update this section to clarify the request distribution
 - **Protocol bypass**: Fallback endpoints bypass protocol-level validation and are sent directly to the configured URLs
 - **Service-specific**: Each service ID can have its own set of fallback endpoints
 
+**`sanction_config` (optional)**
+
+Configures the endpoint sanction system parameters. The sanction system temporarily excludes misbehaving endpoints from selection. When an endpoint returns errors or behaves poorly, it receives a "session sanction" that prevents it from being selected for requests until the sanction expires.
+
+```yaml
+gateway_config:
+  # ... other fields ...
+  sanction_config:
+    session_sanction_duration: "30m"  # How long session sanctions last
+    cache_cleanup_interval: "5m"       # How often to purge expired sanctions
+```
+
+| Field                       | Type   | Required | Default | Description                                                                                              |
+| --------------------------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------- |
+| `session_sanction_duration` | string | No       | "1h"    | Duration that session-based sanctions remain active. Format: Go duration string (e.g., "30m", "1h", "2h") |
+| `cache_cleanup_interval`    | string | No       | "10m"   | Interval for purging expired sanction entries from the cache. Format: Go duration string                 |
+
+**Key Features:**
+- **Automatic expiration**: Session sanctions automatically expire after the configured duration
+- **Configurable timing**: Operators can tune sanction duration based on their network conditions
+- **Memory efficient**: Expired sanctions are periodically cleaned up to prevent memory bloat
+
+**Use Cases:**
+- **Shorter durations** (e.g., `15m`): Use when endpoints frequently have temporary issues and you want faster recovery
+- **Longer durations** (e.g., `2h`): Use when you want to more aggressively exclude problematic endpoints
+- **Default** (`1h`): Balanced approach suitable for most deployments
+
+**`reputation_config` (optional)**
+
+Configures the endpoint reputation system. Unlike binary sanctions that simply exclude or include endpoints, the reputation system provides **gradual scoring** based on endpoint reliability patterns over time. This allows for more nuanced endpoint selection and softer handling of temporarily degraded endpoints.
+
+```yaml
+gateway_config:
+  # ... other fields ...
+  reputation_config:
+    enabled: true                    # Enable the reputation system
+    storage_type: "memory"           # Storage backend (currently only "memory" supported)
+    initial_score: 80                # Starting score for new endpoints
+    min_threshold: 30                # Score below which endpoints are filtered out
+    recovery_timeout: "5m"           # Time after which inactive endpoints can be re-evaluated
+```
+
+| Field              | Type    | Required | Default | Description                                                                                        |
+| ------------------ | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------- |
+| `enabled`          | boolean | No       | false   | Whether to enable the reputation system. When false, only binary sanctions are used.               |
+| `storage_type`     | string  | No       | "memory"| Storage backend for reputation data. Currently only "memory" is supported.                         |
+| `initial_score`    | float64 | No       | 80      | Starting reputation score for new endpoints (0-100 scale).                                         |
+| `min_threshold`    | float64 | No       | 30      | Minimum score required for an endpoint to be considered for selection.                             |
+| `recovery_timeout` | string  | No       | "5m"    | Duration after which inactive endpoint scores can be re-evaluated. Format: Go duration string.     |
+
+**How Reputation Scoring Works:**
+
+The reputation system records **signals** for each endpoint interaction:
+
+| Signal Type      | Impact | Description                                                    |
+| ---------------- | ------ | -------------------------------------------------------------- |
+| Success          | +1     | Successful request/response                                    |
+| Minor Error      | -3     | Client errors, unknown errors (not endpoint's fault)           |
+| Major Error      | -10    | Timeouts, connection issues (recoverable)                      |
+| Critical Error   | -25    | HTTP 5xx, validation errors (service degradation)              |
+| Fatal Error      | -50    | Service misconfiguration (previously "permanent sanction")     |
+
+**Key Features:**
+- **Gradual scoring**: Endpoints build or lose reputation over time based on actual performance
+- **Soft degradation**: Instead of immediately excluding endpoints, scores gradually decrease
+- **Recovery path**: Endpoints can recover reputation through consistent successful responses
+- **Works with sanctions**: Reputation filtering is applied **in addition to** binary sanctions, not as a replacement
+
+**Prometheus Metrics:**
+
+When reputation is enabled, the following metrics are exported:
+
+| Metric Name                                  | Type      | Description                                              |
+| -------------------------------------------- | --------- | -------------------------------------------------------- |
+| `path_shannon_reputation_signals_total`      | Counter   | Total signals by service_id, signal_type, endpoint_domain |
+| `path_shannon_reputation_endpoints_filtered_total` | Counter | Endpoints filtered vs allowed by service_id, action, domain |
+| `path_shannon_reputation_score_distribution` | Histogram | Distribution of endpoint scores by service_id            |
+| `path_shannon_reputation_errors_total`       | Counter   | Errors in the reputation system by operation, error_type |
+
+**Use Cases:**
+- **Production deployments**: Enable to get gradual endpoint scoring and better resilience
+- **Debugging**: Use metrics to identify consistently problematic endpoints or domains
+- **Tuning**: Adjust `min_threshold` based on your network's reliability patterns
+
+:::warning E2E Testing
+When running E2E tests with reputation enabled, ensure `reputation_config.enabled: true` is set in your test configuration (e.g., `e2e/config/.shannon.config.yaml`). Without this, E2E tests will not exercise the reputation code path.
+:::
+
 ---
 
 ## `hydrator_config` (optional)