# ProviderCheckpoint.sol

The `ProviderCheckpoint` contract manages state tracking, checkpoint creation, and reward distribution for Providers. It integrates with other system components, including the Router, to facilitate operations like staking, unstaking, and rewards management.

***

## Key Features

1. **Provider Checkpoints**:
   * Tracks provider-related operations (e.g., staking, unstaking, rewards) using operation checkpoints.
2. **Scheduler Integration**:
   * Creates scheduler checkpoints for models to aggregate and finalize shard contributions and rewards.
3. **Reward Management**:
   * Tracks and finalizes provider reward checkpoints for specific epochs.
4. **Access Control**:
   * Securely restricts functions to admin or scheduler roles.
5. **Router Integration**:
   * Facilitates interactions with other system components via the Router.

***

## Roles

### Access Control

The contract uses `AccessControl` to manage roles and permissions.

* **`DEFAULT_ADMIN_ROLE`**:
  * Grants full administrative access to the contract.
* **`SCHEDULER_ROLE`**:
  * Allows schedulers to perform operations like creating checkpoints.

***

## State Variables

* **Router Reference**:
  * `router`: The Router contract used to interact with other system components.
* **Checkpoint Mappings**:
  * `providerSchedulerCheckpoints`: Maps model IDs and epochs to scheduler checkpoints.
  * `providerOperationCheckpoints`: Maps model IDs to an array of operation checkpoints.
  * `providerOperationCheckpointsByEpoch`: Maps model IDs and epochs to an array of operation checkpoints.
  * `providerRewardCheckpoints`: Maps provider IDs and epochs to reward checkpoints.
  * `shardSumsForEpoch`: Tracks the sum of shards for each model ID and epoch.
  * `providerShardsInEpoch`: Tracks provider shards for each model ID and epoch.
  * `rewardCheckpointBatch`: Tracks the reward batch ID for each model ID and epoch.
* **Last Updated Epoch**:
  * `lastSchedulerUpdatedEpochForModel`: Tracks the last epoch where a scheduler checkpoint was updated for each model.

***

## Key Functions

### Constructor

#### `constructor(IRouter _router)`

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

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

***

### Checkpoint Creation

#### `createProviderRewardsCheckpoints`

Creates provider reward checkpoints for a specified model ID and epoch.

* **Parameters**:
  * `_batchId`: The reward batch ID.
  * `_modelId`: The ID of the model.
  * `_epoch`: The epoch for the rewards.
  * `_providerShards`: Array of provider shards contributing to the rewards.
* **Access Control**:
  * Callable by accounts with `DEFAULT_ADMIN_ROLE` or `SCHEDULER_ROLE`.

***

#### `createProviderSchedulerCheckpoint`

Creates a scheduler checkpoint for a specified model ID and epoch.

* **Parameters**:
  * `_modelId`: The ID of the model.
  * `_epoch`: The epoch for the checkpoint.
  * `_totalShards`: Total shards in the epoch.
  * `_totalRewardsForEpoch`: Total rewards for the epoch.
  * `_expectedRewardBatchId`: The expected batch ID for rewards.
* **Access Control**:
  * Callable by accounts with `DEFAULT_ADMIN_ROLE` or `SCHEDULER_ROLE`.

***

#### `createProviderOperationCheckpoint`

Creates an operation checkpoint for a specific provider.

* **Parameters**:
  * `_id`: The ID of the provider.
  * `_amount`: The amount involved in the operation.
  * `_poolBalanceAfterOperation`: The balance after the operation.
  * `_operation`: The type of operation (unstake, stake, or claim rewards).
* **Access Control**:
  * Callable only by authorized staking addresses.

***

### Data Retrieval

#### `getProviderSchedulerCheckpoint`

Retrieves the scheduler checkpoint for a specified model ID and epoch.

* **Parameters**:
  * `_modelId`: The ID of the model.
  * `_epoch`: The epoch for which the checkpoint is requested.
* **Returns**:
  * A `ProviderSchedulerCheckpoint` struct.

***

#### `getProviderOperationCheckpoints`

Retrieves all operation checkpoints for a specified model ID.

* **Parameters**:
  * `_modelId`: The ID of the model.
* **Returns**:
  * An array of `ProviderOperationCheckpoint` structs.

***

#### `getProviderOperationCheckpointsByEpoch`

Retrieves operation checkpoints for a specific model ID and epoch.

* **Parameters**:
  * `_modelId`: The ID of the model.
  * `_epoch`: The epoch for which the checkpoints are requested.
* **Returns**:
  * An array of `ProviderOperationCheckpoint` structs.

***

#### `getProviderRewardCheckpoint`

Retrieves the reward checkpoint for a specific provider ID and epoch.

* **Parameters**:
  * `_id`: The ID of the provider.
  * `_epoch`: The epoch for which the reward checkpoint is requested.
* **Returns**:
  * A `ProviderRewardCheckpoint` struct.

***

## Events

* **`ProviderSchedulerCheckpointUpdated(uint256 indexed modelId, uint256 indexed epoch)`**:
  * Emitted when a scheduler checkpoint is updated.
* **`ProviderOperationCheckpointUpdated(bytes id, uint256 amount, uint8 operation)`**:
  * Emitted when an operation checkpoint is created.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.function.network/function-network/contracts/providercheckpoint.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.