# Permissions.sol

The `Permissions` contract manages the whitelisting and jailing of Gateways and Providers within the system. It ensures secure access control through role-based mechanisms and integrates with other components for entity registration and epoch management.

***

## Key Features

1. **Whitelisting**:
   * Enables adding or removing Gateways and Providers to/from the whitelist.
   * Entities must be registered before they can be whitelisted.
2. **Jailing**:
   * Allows Gateways or Providers to be temporarily jailed for a specified number of epochs.
   * Supports unjailing entities manually.
3. **Access Control**:
   * Role-based access for admins and whitelisters to manage entities securely.
4. **Batch Processing**:
   * Supports batch operations with a defined maximum batch size to optimize gas usage.

***

## Roles

### Access Control

The contract employs `AccessControl` for secure operations.

* **`DEFAULT_ADMIN_ROLE`**:
  * Grants full administrative privileges for managing the contract.
* **`WHITELISTER_ROLE`**:
  * Allows managing the whitelist and jailing entities.

***

## State Variables

* **`router`**:
  * Reference to the `Router` contract for system-wide integrations.
* **`PROVIDER` / `GATEWAY`**:
  * Constants representing the entity types:
    * `PROVIDER = 0`
    * `GATEWAY = 1`
* **`providerJailedTilEpoch` / `gatewayJailedTilEpoch`**:
  * Mappings of entity IDs to the epoch until which they are jailed.
* **`providerWhitelist` / `gatewayWhitelist`**:
  * Mappings of entity IDs to their whitelist status.
* **`MAX_BATCH_SIZE`**:
  * The maximum number of entities that can be processed in a single batch operation (default: 100).

***

## Key Functions

### Constructor

#### `constructor(IRouter _router)`

Initializes the contract and assigns the deployer the `DEFAULT_ADMIN_ROLE`.

* **Parameters**:
  * `_router`: Address of the `Router` contract.

***

### Whitelisting Functions

#### `whitelisted(bytes calldata _id, uint8 _type) -> bool`

Checks if a Gateway or Provider is whitelisted and not jailed.

* **Parameters**:
  * `_id`: The ID of the entity.
  * `_type`: The entity type (`0` for Provider, `1` for Gateway).
* **Returns**:
  * `true` if the entity is whitelisted and not jailed, otherwise `false`.

***

#### `whitelist(bytes[] calldata _ids, uint8 _type)`

Adds a batch of IDs to the whitelist.

* **Parameters**:
  * `_ids`: Array of IDs to whitelist.
  * `_type`: The entity type (`0` for Provider, `1` for Gateway).
* **Access Control**:
  * Callable by accounts with `DEFAULT_ADMIN_ROLE` or `WHITELISTER_ROLE`.

***

#### `removeFromWhitelist(bytes[] calldata _ids, uint8 _type)`

Removes a batch of IDs from the whitelist.

* **Parameters**:
  * `_ids`: Array of IDs to remove.
  * `_type`: The entity type (`0` for Provider, `1` for Gateway).
* **Access Control**:
  * Callable by accounts with `DEFAULT_ADMIN_ROLE` or `WHITELISTER_ROLE`.

***

### Jailing Functions

#### `jailForEpochs(bytes calldata _id, uint8 _type, uint256 _numEpochs)`

Temporarily jails a Gateway or Provider for a specified number of epochs.

* **Parameters**:
  * `_id`: The ID of the entity.
  * `_type`: The entity type (`0` for Provider, `1` for Gateway).
  * `_numEpochs`: The number of epochs to jail the entity.
* **Access Control**:
  * Callable by accounts with `DEFAULT_ADMIN_ROLE` or `WHITELISTER_ROLE`.

***

#### `unjail(bytes calldata _id, uint8 _type)`

Manually unjails a Gateway or Provider.

* **Parameters**:
  * `_id`: The ID of the entity.
  * `_type`: The entity type (`0` for Provider, `1` for Gateway).
* **Access Control**:
  * Callable by accounts with `DEFAULT_ADMIN_ROLE` or `WHITELISTER_ROLE`.

***

## Events

* **`Whitelisted(bytes id, uint8 indexed type)`**:
  * Emitted when an entity is added to the whitelist.
* **`RemovedFromWhitelist(bytes id, uint8 indexed type)`**:
  * Emitted when an entity is removed from the whitelist.
* **`Jailed(bytes id, uint8 indexed type, uint256 numEpochs, uint256 jailUntil)`**:
  * Emitted when an entity is jailed.
* **`Unjailed(bytes id, uint8 indexed type)`**:
  * Emitted when an entity is unjailed.