# Actor Spec: StoragePower

[Back to Master Tracking Doc](https://hackmd.io/LOZjAsz-THelSD5lWqSVlw)

## Contents

[TOC]

## At a Glance

The StoragePower actor has a few roles:
* Entry point into Filecoin for Miners
* Keeps track of created Miner instances, as well as miners with power above consensus threshold
* Manages active Miner instances and associated StoragePower accounting
* Tracks deferred cron events for each Miner, and ensures these events are executed at specific epochs (through `OnEpochTickEnd`)
* Aggregates Proofs of Replication (PoReps) for Miners, and submits them for bulk verification once per epoch
* Updates network KPI via Reward actor.

**Actor Type:**
- Singleton
- Address: 4

**Exported Methods:**

1. Constructor
2. CreateMiner
3. UpdateClaimedPower
4. EnrollCronEvent
5. OnEpochTickEnd
6. UpdatePledgeTotal
7. SubmitPoRepForBulkVerify
8. CurrentTotalPower

## Terms

* **RawBytePower**: A Miner's power in terms of the number of bytes in the Miner's committed sectors.
* **QualityAdjPower**: A Miner's RawBytePower adjusted for the number of deals stored in the Miner's committed sectors.
* **ConsensusMinerMinPower**: The minimum QualityAdjPower a Miner must have in order to qualify for leader election.

## State

type State struct {
    TotalRawBytePower abi.StoragePower
    TotalBytesCommitted abi.StoragePower
    TotalQualityAdjPower abi.StoragePower
    TotalQABytesCommitted abi.StoragePower
    TotalPledgeCollateral abi.TokenAmount
    ThisEpochRawBytePower abi.StoragePower
    ThisEpochQualityAdjPower abi.StoragePower
    ThisEpochPledgeCollateral abi.TokenAmount
    ThisEpochQAPowerSmoothed smoothing.FilterEstimate
    MinerCount            int64
    MinerAboveMinPowerCount int64
    CronEventQueue cid.Cid
    FirstCronEpoch abi.ChainEpoch
    Claims cid.Cid
    ProofValidationBatch *cid.Cid
}

**`TotalRawBytePower`**: The sum of all RawBytePower from all Miners meeting minimum power (ConsensusMinerMinPower)
* Invariants:
* `TotalRawBytePower >= 0`

**`TotalBytesCommitted`**: The sum of all RawBytePower from all Miners, including those that do not meet minimum power (ConsensusMinerMinPower)
* Invariants:
* `TotalBytesCommitted >= TotalRawBytePower`

**`TotalQualityAdjPower`**: The sum of all QualityAdjPower from all Miners meeting minimum power (ConsensusMinerMinPower)
* Invariants:
* `TotalQualityAdjPower >= TotalRawBytePower`

**`TotalQABytesCommitted`**: The sum of all QualityAdjPower from all Miners, including those that do not meet minimum power (ConsensusMinerMinPower)
* Invariants:
* `TotalQABytesCommitted >= TotalQualityAdjPower`

**`TotalPledgeCollateral`**: Current total amount of pledge collateral held across all Miners
* Invariants:
* `TotalPledgeCollateral >= 0`

**`ThisEpochRawBytePower`**: Total RawBytePower of consensus-eligible Miners. Set each cron tick and remains constant until the next cron tick.
* Invariants:
* `ThisEpochRawBytePower >= 0`

**`ThisEpochQualityAdjPower`**: Total QualityAdjPower of consensus-eligible Miners. Set each cron tick and remains constant until the next cron tick.
* Invariants:
* `ThisEpochQualityAdjPower >= 0`

**`ThisEpochPledgeCollateral`**: Total pledge collateral held across all Miners. Set each cron tick and remains constant until the next cron tick.
* Invariants:
* `ThisEpochPledgeCollateral >= 0`

**`ThisEpochQAPowerSmoothed`**: TODO

**`MinerCount`**: The number of Miner actors created via `CreateMiner`, minus the number deleted via `OnConsensusFault`
* Notes:
* Does not factor in ConsensusMinerMinPower
* Invariants:
* `MinerCount >= MinerAboveMinPowerCount`

**`MinerAboveMinPowerCount`**: The number of Miner Claims with a QualityAdjPower above ConsensusMinerMinPower.
* Notes:
* Miners that meet this threshold are eligible for leader election.
* Invariants:
* `MinerAboveMinPowerCount >= 0`

**`CronEventQueue`**: A collection of CronEvents that are sent to specific Miners at specific epochs.
* Notes:
* Cid type: HAMT, `map[ChainEpoch]AMT[CronEvent]`
* Maps a ChainEpoch to an array of CronEvents to process at that epoch.
* See `CronEvent` below

**`FirstCronEpoch`**: The epoch at which cron tick processing will start.
* Invariants:
* `FirstCronEpoch >= 0`

**`Claims`**: A collection of Claims denoting the StoragePower each Miner has accrued.
* Notes:
* Cid type: HAMT, `map[Address]Claim`
* Maps a Miner's address to its Power Claim
* Uses the Miner's ID address
* See `Claim` below

**`ProofValidationBatch`**: A collection of PoReps for each Miner that will be processed on the next invocation of `OnEpochTickEnd`.
* Notes:
* Cid type, HAMT, `map[Address]AMT[SealVerifyInfo]`
* Maps a Miner's address to an array of SealVerifyInfo that will be provided to `rt.Syscalls().BatchVerifySeals`
* Uses the Miner's ID address
* See `SealVerifyInfo` below

#### CronEvent

type CronEvent struct {
	MinerAddr       addr.Address
	CallbackPayload []byte
}

**`MinerAddr`**: The address of the Miner whose `OnDeferredCronEvent` method will be invoked.
* Notes:
* Uses ID addresses

**`CallbackPayload`**: The parameters with which `OnDeferredCronEvent` will be invoked.

#### Claim

A Claim tracks power accrued by a Miner across all active Sectors.

type Claim struct {
    SealProofType abi.RegisteredSealProof
    RawBytePower abi.StoragePower
    QualityAdjPower abi.StoragePower
}

**`SealProofType`**: The type of proof being used by the Miner

**`RawBytePower`**: Sum of RawBytePower for a Miner's Sectors
* Invariants:
* `RawBytePower >= 0`

**`QualityAdjPower`**: Sum of QualityAdjPower for a Miner's Sectors
* Invariants:
* `QualityAdjPower >= 0`

#### SealVerifyInfo

type SealVerifyInfo struct {
    SealProof RegisteredSealProof
    SectorID
    DealIDs               []DealID
    Randomness            SealRandomness
    InteractiveRandomness
    InteractiveSealRandomness
    Proof                 []byte
    SealedCID             cid.Cid
    UnsealedCID           cid.Cid
}

**`SealProof`**: The proof type used by a Miner for sealing Sectors.

**`SectorID`**: The ID of the sector being proven. Combines the Miner's actor ID and the SectorNumber.

**`DealIDs`**: A slice of DealIDs stored in the sector given by `SectorID`

**`Randomness`**: Randomness included before PreCommit. Used to validate proof of replication.

**`InteractiveRandomness`**: Randomness included after PreCommit. Used to validate proof of replication.

**`Proof`**: A Proof of Replication that validates the sealing process has been performed correctly.

**`SealedCID`**: The root hash of the Sealed Sector

**`UnsealedCID`**: The root hash of the Unsealed Sector

## Exported Methods

#### 1. Constructor

func (a Actor) Constructor(rt Runtime, _ *adt.EmptyValue) *adt.EmptyValue

Initializes StoragePower actor state.

#### 2. CreateMiner

func (a Actor) CreateMiner(rt Runtime, params *CreateMinerParams) *CreateMinerReturn

Creates a new Miner actor via the Init actor.
* The new Miner's ID address is inserted into `st.Claims`, and `st.MinerCount` is incremented.

##### Parameters

type CreateMinerParams struct {
    Owner         addr.Address
    Worker        addr.Address
    SealProofType abi.RegisteredSealProof
    Peer          abi.PeerID
    Multiaddrs    []abi.Multiaddrs
}

**`Owner`**: The new Miner's Owner address
* Requirements:
* See Miner actor Constructor for requirements.

**`Worker`**: The new Miner's Worker address
* Requirements:
* See Miner actor Constructor for requirements.

**`SealProofType`**: The proof type used for the Miner's sector commit proofs
* Requirements:
* See Miner actor Constructor for requirements.

**`Peer`**: The Libp2p identity used to connect with this Miner
* Requirements:
* See Miner actor Constructor for requirements.

**`Multiaddrs`**: Slice of Libp2p multi-addresses used to establish connections with this miner
* Requirements:
* See Miner actor Constructor for requirements.

##### Return

type CreateMinerReturn struct {
    IDAddress     addr.Address
    RobustAddress addr.Address
}

**`IDAddress`**: The new Miner's ID address

**`RobustAddress`**: The new Miner's ACTOR address

##### Failure conditions
* Caller is not a Signable actor
* Init actor constructor or Miner actor constructor fails
* Init actor returns bad value, causing CBOR unmarshaling to fail

#### 3. UpdateClaimedPower

func (a Actor) UpdateClaimedPower(rt Runtime, params *UpdateClaimedPowerParams) *adt.EmptyValue

Invoked by a Miner whenever their claimed power changes, which may result from any of the following exported methods:
* Miner.SubmitWindowedPoSt
* Miner.ExtendSectorExpiration
* Miner.TerminateSectors
* Miner.DeclareFaults
* Miner.OnDeferredCronEvent (proving period)
* Miner.ConfirmSectorProofsValid

This method:
* Updates the calling Miner's Claim to reflect the change in power
* Updates StoragePower state to reflect the change in overall power:
* `st.TotalBytesCommitted` and `st.TotalQABytesCommitted` are adjusted directly
* `st.MinerAboveMinPowerCount` is increased by 1 if the change to Miner power puts them above `ConsensusMinMinerPower`
* `st.MinerAboveMinPowerCount` is decreased by 1 if the change to Miner power puts them below `ConsensusMinMinerPower`
* `st.RawBytePower` and `st.TotalQualityAdjPower` are adjusted depending on the Miner's power in relation to `ConsensusMinMinerPower`

##### Parameters

UpdateClaimedPowerParams contains the amount a Miner's power has changed. Both amounts may be positive or negative, signalling an increase or decrease in Miner's power, respectively.

type UpdateClaimedPowerParams struct {
    RawByteDelta         abi.StoragePower
    QualityAdjustedDelta abi.StoragePower
}

**`RawByteDelta`**: The change to the Miner's RawBytePower

**`QualityAdjustedDelta`**: The change to the Miner's QualityAdjPower

##### Failure conditions
* Caller is not a Miner actor
* Miner's Claim not found in `st.Claims`
* Change to Miner's Claim results in a negative value for either field (panic)

#### 4. EnrollCronEvent

func (a Actor) EnrollCronEvent(rt Runtime, params *EnrollCronEventParams) *adt.EmptyValue

This method is invoked by a Miner from any of the following exported methods:
* Miner.Constructor
* Miner.TerminateSectors
* Miner.OnDeferredCronEvent

`EnrollCronEvent` allows a Miner to schedule a CronEvent with the StoragePower actor, which will be processed at some future epoch as part of StoragePower.OnEpochTickEnd.

At the specified epoch (`EventEpoch`), OnEpochTickEnd invokes Miner.OnDeferredCronEvent, supplying a `Payload` that allows the Miner to determine how to handle the CronEvent. There are a few types of `Payload` (defined in `miner_actor.go`):
* **Proving Deadline**: Miners have recurring proving deadlines. At the end of each proving deadline, a scheduled CronEvent prompts the Miner to invoke `Miner.handleProvingDeadline`.
* Among other things, this method will schedule another CronEvent for the next proving deadline.
* **Early Sector Termination**: Sectors are occasionally terminated before their expiration. In this case, the Miner processes as many early terminations as possible, and schedules additional terminations for processing at a future epoch.

If an enrolled CronEvent has an `EventEpoch` before `st.FirstCronEpoch`, `st.FirstCronEpoch` is set to `EventEpoch`.

##### Parameters

type EnrollCronEventParams struct {
    EventEpoch abi.ChainEpoch
    Payload    []byte
}

**`EventEpoch`**: The epoch at which the CronEvent will be processed.
* Requirements:
* `EventEpoch >= 0`

**`Payload`**: The payload that will be supplied to Miner.OnDeferredCronEvent.

##### Failure conditions
* Caller is not a Miner actor
* `params.EventEpoch < 0`

#### 5. OnEpochTickEnd

func (a Actor) OnEpochTickEnd(rt Runtime, _ *adt.EmptyValue) *adt.EmptyValue

`OnEpochTickEnd` is a special method invoked by the Cron actor at the end of each tipset.

`OnEpochTickEnd` has 3 responsibilities:
* **Batch Verify PoReps**: If `st.ProofValidationBatch` contains proofs-of-replication (PoRep) submitted by Miners, these are verified in bulk via `rt.Syscalls().BatchVerifySeals`. For each Miner with successfully-proven Sectors, Miner.ConfirmSectorProofsValid is invoked and provided the successfully-proven SectorNumbers.
* After processing the PoReps in `st.ProofValidationBatch`, `st.ProofValidationBatch` is set to `nil`
* Miners that do not have valid Claims will have proof verification skipped.
* See SubmitPoRepForBulkVerify for more info.
* **Process Deferred CronEvents**: Iterates over `st.CronEventQueue` for each epoch from `st.FirstCronEpoch` to `rt.CurrEpoch()`. Each CronEvent is processed by invoking the specified Miner's OnDeferredCronEvent method.
* If a Miner's CronEvent fails, their Claim is zeroed out and deleted as a penalty.
* This method does not process deferred cron events for Miners without valid Claims (it skips them).
* Once CronEvents are processed, `st.FirstCronEpoch` is set to `rt.CurrEpoch() + 1`.
* See EnrollCronEvent for more info.
* **Update Network KPI**: As the last action taken, StoragePower updates its current epoch values for pledge collateral, quality-adjusted power, smoothed quality-adjusted power, and raw byte power. This last value, `st.ThisEpochRawBytePower`, is passed to Reward.UpdateNetworkKPI.

##### Failure conditions
* Caller is not the Cron actor
* Invocation of Reward.UpdateNetworkKPI fails

#### 6. UpdatePledgeTotal

func (a Actor) UpdatePledgeTotal(rt Runtime, pledgeDelta *abi.TokenAmount) *adt.EmptyValue

Each time a Miner's active Sectors change, their pledge total is updated and this method is invoked.

`pledgeDelta` may be a positive or negative value, signifying a gain or loss respectively.

##### Failure conditions
* Caller is not a Miner actor
* Caller does not have a valid claim in `st.Claims`
* Change causes `st.TotalPledgeCollateral` to be negative

#### 7. Deprecated1

This method was deprecated. See [this PR](https://github.com/filecoin-project/specs-actors/pull/1095).

#### 8. SubmitPoRepForBulkVerify

func (a Actor) SubmitPoRepForBulkVerify(rt Runtime, sealInfo *abi.SealVerifyInfo) *adt.EmptyValue

This method is invoked by Miner.ProveCommitSector. When ProveCommitting a Sector, a Miner submits a proof-of-replication (PoRep) to the StoragePower actor via `SubmitPoRepForBulkVerify`.

`SubmitPoRepForBulkVerify` inserts the Miner's proof in `st.ProofValidationBatch`. At the end of the same epoch, StoragePower.OnEpochTickEnd will batch-verify all submitted PoReps.

##### Failure conditions
* Caller is not a Miner actor
* Caller does not have a valid claim in `st.Claims`
* Caller has submitted `MaxMinerProveCommitsPerEpoch` (8000) already

#### 9. CurrentTotalPower

func (a Actor) CurrentTotalPower(rt Runtime, _ *adt.EmptyValue) *CurrentTotalPowerReturn

This method is a simple getter which returns the total power and pledge collateral recorded by the StoragePower actor during the last cron tick. This method is a simple read of these state fields:
* `st.ThisEpochRawBytePower`: Sum of RawBytePower for consensus-eligible Miners
* `st.ThisEpochQualityAdjPower`: Sum of QualityAdjPower for consensus-eligible Miners
* `st.ThisEpochPledgeCollateral`: Sum of pledge collateral across all Miners
* `st.ThisEpochQAPowerSmoothed`: TODO