Skip to content

Commit

Permalink
FIP-0045 updates:
Browse files Browse the repository at this point in the history 
- Specify `HasVerifiedClaims` field in `SectorOnChainInfo`
- Remove opt-in migration for existing sectors
- Add maximum expiration parameter for allocations
- Describe migration for pending deals
  • Loading branch information
@anorth
anorth committed Sep 5, 2022
1 parent d7aeedb commit f9ca4f6
Showing 1 changed file with 64 additions and 62 deletions.
126 changes: 64 additions & 62 deletions FIPS/fip-0045.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,10 @@ requires: FIP-0034
---

TODO:
- Re-spec ExtendClaimTerms as a token receiver hook value rather than explicit method
- Spec methods for sector migration on miner, market, and verifreg actors
- Spec change to SectorOnChainInfo to distinguish migrated sectors
- Figure out best migration plan for pending deals, pre-committed sectors
- Confirm policy for built-in market actor's default term maximum
- Spec token receiver hook payload schema for allocation requests
- Spec token receiver hook payload for extending allocations with new datacap
- Market method for fetching allocation/claim ids for deals (needed?)
- Spec hook/method for a different client extending the claim by spending DataCap (needed?).
- Consider removing provision for re-commitment of same data in new sector (defer to follow-up)


## Simple Summary
Expand Down Expand Up @@ -83,7 +80,7 @@ and is much simpler than the Filecoin Plus premium proposal that also attempted
- *Claim*: a provider's assertion they are storing all or part of an allocation
- *Term*: period of time for which a DataCap allocation or claim is valid or active.

### Data cap allocations
### Verified Registry DataCap allocations

The Filecoin Plus verified registry actor is extended to record allocations of DataCap to specific
pieces of data to be stored by a provider. An allocation is independent of any deal with the
Expand Down Expand Up @@ -114,14 +111,17 @@ struct Allocation {
```

An allocation specifies a range of terms for which the provider may commit the data, between some
minimum and maximum. An allocation's maximum term must be at least as large as its minimum term.

minimum and maximum.
An allocation's maximum term must be at least as large as its minimum term.
Due to the implementation of term enforcement (details below), clients should leave a large buffer
between the minimum and maximum term to make the allocation practical for a provider.

An allocation must expire, so that it cannot occupy non-useful DataCap indefinitely.

**Parameters**
- The minimum allowed value for `TermMinimum` is 6 months.
- The maximum allowed value for `TermMaximum` is 5 years (can be increased by a future FIP).
- The maximum difference between `Expiration` and the epoch at which an allocation is created is 60 days.

Allocations are stored in the verified registry actor's state, grouped by client address.
Nesting by client promotes more efficient lookups at scale,
Expand All @@ -135,12 +135,12 @@ struct State {
Allocations: HAMT[Address]HAMT[AllocationID]Allocation
// Sequence number for allocation IDs.
// The value `0` is reserved for "no allocation"
NextAllocationId: AllocationID // uint64
}
```

#### Operations

An allocation is created by a verified client by transferring DataCap tokens (see below)
to the verified registry.
The `Allocation` metadata must be provided as transfer metadata.
Expand Down Expand Up @@ -169,7 +169,7 @@ The `RemoveVerifiedClientDataCap` method invokes a privileged method of the Data
to burn DataCap tokens held on a client's balance.
Only the verified registry actor is permitted to invoke this method.

### Data cap claims
### Verified Registry DataCap claims

The verified registry actor is further extended to record each storage provider's commitment to a
DataCap allocation, called a claim. A claim represents a provider's obligation to store a piece of
Expand Down Expand Up @@ -258,24 +258,14 @@ struct RemoveExpiredClaimsParams {
fn RemoveExpiredClaims(params: RemoveExpiredClaimsParams)
```


The maximum term for a claim may be increased by the client which originally made the allocation,
up to the network policy maximum.

A verified client can extend the term for a claim _beyond_ the initial maximum term by
spending new DataCap.
The term maximum can be extended up to the network policy maximum beyond the current epoch.
The client extending the claim need not be the one that made the original allocation.
This is similar to issuing a new allocation/claim for the same data,
but avoids overheads of re-sealing.

TODO: rework this to be a token receiver hook rather than explicit method

```
struct ClaimTerm {
Provider: Address // needed to find claim in state
ClaimID: ClaimID
TermMaximum: int64 // duration in epochs
TermMaximum: int64 // new duration in epochs from TermStart
}
struct ExtendClaimTermsParams{
Claims: []ClaimTerm
Expand All @@ -294,6 +284,16 @@ struct ExtendClaimTermsResult {
fn ExtendClaimTerms(params: ExtendClaimTermsParams) -> ExtendClaimTermsResult
```

A verified client can extend the term for a claim _beyond_ the initial maximum term by
spending new DataCap.
The term maximum can be extended up to the network policy maximum beyond the current epoch.
The client extending the claim need not be the one that made the original allocation.
This is similar to issuing a new allocation/claim for the same data,
but avoids overheads of re-sealing.

TODO: spec token receiver hook for extending


### Data cap token
The `VerifiedClients` map of addreses to balances is removed from the verified registry state.
The balances of DataCap tokens held by verified clients are extracted to a DataCap token actor.
Expand Down Expand Up @@ -325,16 +325,16 @@ The built-in account and multisig actors are changed to implement a receiver hoo
This hook always succeeds, without inspecting the payload.

#### Operations
The `AddVerifiedClient` method is changed to invoke the DataCap token actor to
The verified registry's `AddVerifiedClient` method is changed to invoke the DataCap token actor to
mint new tokens to the client's balance.

The `UseBytes` method is removed.
The verified registry's `UseBytes` method is removed.
To create an allocation, a verified client transfers DataCap tokens to the verified registry actor.
The transfer must be accompanied by one or more `Allocation` records which specify
the allocation(s) to create.
The registry may reject the transfer if the allocations are invalid.

The `RestoreBytes` method is also removed.
The verified registry's `RestoreBytes` method is also removed.
Instead, the `RevokeAllocations` method on the verified registry actor transfers any released
DataCap tokens back to the client's balance for re-use.

Expand Down Expand Up @@ -375,7 +375,30 @@ The pledge requirement for the old sector is not decreased,
but any subsequent penalty is calculated using its current (i.e. reduced) power.

### Storage miner actor
The built-in miner actor is trusted to enforce the verified and the continual storage of the data.
#### Differentiated sectors
A new field `HasVerifiedClaims: bool` is added to `SectorOnChainInfo`.
This is set `false` for all existing sectors during migration (below).

A _new_ sector takes `HasVerifiedClaims = true` if it claims one or more verified allocations.
Its `DealWeight` and `VerifiedDealWeight` will be a simple sum of the size of those claims.
Its power is calculated in the simple way described above.

A _new_ sector takes `HasVerifiedClaims = false` if it claims no verified allocations.

A sector with `HasVerifiedClaims = false` and `VerifiedDealWeight = 0`
(i.e. a committed-capacity sector) takes `HasVerifiedClaims = true` if it claims
one or more verified allocations by `ReplicaUpdate`.
Its new `DealWeight` and `VerifiedDealWeight` are calculated as a sum of the size of those claims.
Its power is re-calculated in the simple way described above.

A sector with `HasVerifiedClaims = false` and `VerifiedDealWeight > 0` continues to use
the existing QA-power calculation.
Such a sector cannot claim a verified allocation.
Such a sector may be extended, but, as today, this will result in its power being diluted
to "spread out" the verified reward over the sector's new commitment duration.

#### Term enforcement
The built-in miner actor enforces the verified term and the continual storage of the data.

The miner actor requires that the sector into which a claimed piece is committed must have a
**remaining lifespan that is sufficient to fulfil the minimum term**.
Expand Down Expand Up @@ -404,7 +427,7 @@ The miner actor must ensure that the old sector is no longer alive.

#### Sector extension
A sector's scheduled commitment term cannot be extended beyond the maximum term of any
verified claim attributed to it.
verified claim attributed to it (if `HasVerifiedClaims = true`).
Thus, to extend a sector, a provider must simultaneously drop any verified claims with
terms that would be exceeded by the extended commitment.
Dropping a verified claim reduces the sector's power accordingly, as well as
Expand Down Expand Up @@ -480,7 +503,7 @@ The built-in market specifies an allocation's minimum term to be equal to the de
and maximum term to be some amount greater than the deal duration.

**Parameters**
- The built-in market calculates a term maximum of 1 year greater than a deal's specified duration.
- The built-in market calculates a term maximum of 90 days greater than a deal's specified duration.

```
let dealAllocation = Allocation {
Expand All @@ -490,11 +513,14 @@ let dealAllocation = Allocation {
Size: deal.PieceSize
TermMinimum: deal.EndEpoch - deal.StartEpoch
TermMaximum: deal.EndEpoch - deal.StartEpoch + EPOCHS_IN_YEAR
Expiration: deal.StartEpoch
Expiration: min(deal.StartEpoch, CURRENT_EPOCH + 60 * EPOCHS_IN_DAY)
AllowRanges: false
}
```

The market will accept verified deals with a `StartEpoch` beyond the maximum allowed allocation `Expiration`.
If such a deal is not activated before the allocation expires, it will not confer QA power.

The market stores allocation IDs for not-yet-activated deals in a new mapping,
and the claim ID for activated deals in deal state.

Expand Down Expand Up @@ -526,43 +552,19 @@ The miner actor then invokes `ClaimAllocations` and, if successful,
computes quality adjusted power for the sector according to the piece size and QA power multiplier.

### Migration
#### Network upgrade
A network state migration is required to implement this proposal.

That migration must:
- Implement the new verified registry state schema for allocations and claims.
- Implement the new verified registry state schema for allocations and claims,
and set `NextAllocationId = 1`.
- Migrate the verified registry client balances map to DataCap token balances,
with appropriate unit conversion.
- Add a new field to SectorOnChainInfo identifying whether its quality-adjusted power is calculated
according to the old spread-out method, or the new direct method
- TODO: handle pending deals: either create allocations or keep not-yet-proven sectors in the old world.

#### Opt-in per-sector
The power for existing sectors is not changed by this proposal.

A provider may opt in to migrate a sector to the new QA power calculation method by invoking a new method.
Each active deal is converted to a claim as if an allocation had been created when the deal was made.
The claim's minimum term is the deal's duration, and maximum term is the greater of either
the sector's current expiration epoch, or 540 days beyond the current epoch
(since the provider could extend the sector to such lifetime prior to migrating).

Expired deals cannot be migrated, even though the old QA power calculation method has spread out
their power and reward over the sector's full lifetime.
This will generally result in an increase in power for a sector,
but may result in a decrease in case of expired deals.
This is why the migration is opt-in.

A new method on the storage miner actor:
- Fetches information about each not-yet-expired verified deal from the market
- Calls the verified registry to create a claim for each such deal.
- Re-calculates power according to the amount of space committed to active claims.
- Re-caclulates pledge requirement according to the new power and network conditions (but never decreases)

After migration, the client can extend the migrated claims' terms up to the network policy maximum.
After claims are extended, the provider can extend the sector commitment duration to match.
Note that a migrated sector cannot be extended unless the claim terms are extended,
lest it violate a claim's maximum term.

TODO: specify migration method and changes to SectorOnChainInfo
- Add a new field `HasVerifiedClaim = false` to each `SectorOnChainInfo`.
- Add the pending allocation mapping to market state, and claim ID field to deal states (all `0`)
- For each pending (not yet activated) deal with `Verified = true`, create an Allocation
- The maximum term for such allocations is 540 days, in order to support any possible sector duration
- The expiration for such allocations is set to the maximum allowed value after the migration epoch,
which may be before the deal's start date.

## Design Rationale
The design rationale is mostly provided by the proposal's motivation.
Expand Down

0 comments on commit f9ca4f6

Please sign in to comment.