github.com/onflow/flow-go@v0.35.7-crescendo-preview.23-atree-inlining/network/alsp/manager/README.md (about)

     1  # Application Layer Spam Prevention (ASLP) Manager
     2  Implementation of ALSP manager is available here: [manager.go](manager.go)
     3  Note that this readme is primarily focusing on the ALSP manager. For more details regarding the ALSP system please refer to [readme.md](..%2Freadme.md).
     4  ---
     5  ## Architectural Overview
     6  ### Reporting Misbehavior and Managing Node Penalties
     7  Figure below illustrates the ALSP manager’s role in the reporting of misbehavior and the management of node penalties as
     8  well as the interactions between the ALSP manager and the `LibP2PNode`, `ConnectionGater`, and `PeerManager` components for 
     9  the disallow listing and allow listing processes.
    10  
    11  #### Reporting Misbehavior
    12  In the event that an engine detects misbehavior within a channel, 
    13  it is imperative to report this finding to the ALSP manager. 
    14  This is achieved by invoking the `ReportMisbehavior` method on the conduit corresponding to the engine.
    15  
    16  #### Managing Penalties
    17  The ALSP manager is responsible for maintaining records of misbehavior reports associated with
    18  remote nodes and for calculating their accumulated misbehavior penalties. 
    19  Should a node’s misbehavior penalty surpass a certain threshold 
    20  (referred to as `DisallowListingThreshold`), the ALSP manager initiates the disallow listing process. When a remote node is disallow-listed,
    21  it is effectively isolated from the network by the `ConnectionGater` and `PeerManager` components, i.e., the existing 
    22  connections to that remote node are closed and new connections attempts are rejected.
    23  
    24  ##### Disallow Listing Process
    25  1. The ALSP manager communicates with the `LibP2PNode` by calling its `OnDisallowListNotification` method to indicate that a particular remote node has been disallow-listed.
    26  2. In response, the `LibP2PNode` takes two important actions:
    27  
    28     a. It alerts the `PeerManager`, instructing it to sever the connection with the disallow-listed node.
    29     b. It notifies the `ConnectionGater` to block any incoming or outgoing connections to and from the disallow-listed node.
    30  This ensures that the disallow-listed node is effectively isolated from the local node's network.
    31  
    32  ##### Penalty Decay and Allow Listing Process
    33  The ALSP manager also includes a penalty decay mechanism, which gradually reduces the penalties of nodes over time upon regular heartbeat intervals (default is every one second).
    34  Once a disallow-listed node's penalty decays back to zero, the node can be reintegrated into the network through the allow listing process. The allow-listing process involves allowing
    35  the `ConnectionGater` to lift the block on the disallow-listed node and instructing the `PeerManager` to initiate an outbound connection with the allow-listed node.
    36  
    37  1. The ALSP manager calls the `OnAllowListNotification` method on the `LibP2PNode` to signify that a previously disallow-listed node is now allow-listed.
    38  2. The `LibP2PNode` responds by:
    39  
    40     a. Instructing the `ConnectionGater` to lift the block, thereby permitting connections with the now allow-listed node.
    41     b. Requesting the `PeerManager` to initiate an outbound connection with the allow-listed node.
    42  
    43  This series of actions allows the rehabilitated node to be reintegrated and actively participate in the network once again.
    44  ![alsp-manager.png](alsp-manager.png)
    45  ---
    46  
    47  
    48  
    49  ## Developer Guidelines
    50  The ALSP (Application Layer Spam Prevention) Manager handles application layer spamming misbehavior reports and penalizes misbehaving nodes. It also disallow-lists nodes whose penalties drop below a threshold.
    51  
    52  
    53  - **Misbehavior Reports**: When a local engine detects a spamming misbehavior of a remote node, it sends a report to the ALSP manager, by invoking the `HandleMisbehaviorReport` method of the corresponding
    54  conduit on which the misbehavior was detected. The manager handles the report in a thread-safe and non-blocking manner, using worker pools.
    55  
    56  ```go
    57  func (m *MisbehaviorReportManager) HandleMisbehaviorReport(channel channels.Channel, report network.MisbehaviorReport) {
    58      // Handle the report
    59  }
    60  ```
    61  
    62  - **Penalties**: Misbehaving nodes are penalized by the manager. 
    63  The manager keeps a cache of records with penalties for each node. 
    64  The penalties are decayed over time through periodic heartbeats.
    65  
    66  - **Disallow-listing**: Nodes whose penalties drop below a threshold are disallow-listed.
    67  
    68  - **Heartbeats**: Periodic heartbeats allow the manager to perform recurring tasks, such as decaying the penalties of misbehaving nodes.
    69  ```go
    70  func (m *MisbehaviorReportManager) heartbeatLoop(ctx irrecoverable.SignalerContext, interval time.Duration) {
    71      // Handle heartbeats
    72  }
    73  ```
    74  
    75  - **Disallow-list Notification Consumer**: is the interface of the consumer of disallow-list notifications, which is 
    76  responsible for taking actions when a node is disallow-listed, i.e., closing exisitng connections with the remote disallow-listed 
    77  node and blocking any incoming or outgoing connections to that node. The consumer is passed to the manager when it is created.
    78  In the current implementation the consumer is the instance of the `LibP2PNode` component of the node.
    79  ```go
    80  disallowListingConsumer network.DisallowListNotificationConsumer
    81  ```
    82  
    83  ### Configuration
    84  The configuration includes settings like cache size, heartbeat intervals, and network type.