From d0f42f441345979c73b5b7c6b4677a96eb11f988 Mon Sep 17 00:00:00 2001 From: Rod Vagg Date: Fri, 15 Mar 2024 15:58:23 +1100 Subject: [PATCH 1/2] FIP-0045: update to match deployed types * Many of the type fields marked as Address in here were launched in nv9 as ActorID. * AllocationRequest and ClaimExtensionRequest went live in nv9 with Provider as Address but in nv10 switched to ActorID. * ClaimExtensionRequest was never adjusted in go-state-types to ActorID so has been unable to successfully parse or pass on these to builtin-actors. ExtendClaimTerms appears to have been the only mechanism used to extend claim terms since this FIP. * Minor: updated all epoch fields to match within this FIP, I chose to use int64 which is the base type used in implementations. * Add missing docs for AllocationRequest and ClaimExtensionRequest fields. * Added historical notes section. --- FIPS/fip-0045.md | 68 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 47 insertions(+), 21 deletions(-) diff --git a/FIPS/fip-0045.md b/FIPS/fip-0045.md index 46e826f6..c9a7ce3f 100644 --- a/FIPS/fip-0045.md +++ b/FIPS/fip-0045.md @@ -84,21 +84,21 @@ built-in storage market (or any future market). ``` struct Allocation { // The verified client which allocated the DataCap. - Client: Address + Client: ActorID // The provider (miner actor) which may claim the allocation. - Provider: Address + Provider: ActorID // Identifier of the data to be committed. Data: CID // The (padded) size of data. Size: uint64 // The minimum duration which the provider must commit to storing the piece to avoid // early-termination penalties (epochs). - TermMinimum: uint64 + TermMinimum: int64 // The maximum period for which a provider can earn quality-adjusted power // for the piece (epochs). - TermMaximum: uint64 + TermMaximum: int64 // The latest epoch by which a provider must commit data before the allocation expires. - Expiration: Epoch + Expiration: int64 // Whether the provider can commit the data in multiple pieces. // This is initially un-used, but supports allocations larger than a full sector in the future. AllowRanges: bool @@ -129,7 +129,7 @@ struct State { // Allocations indexed by client, then by ID. Allocations: HAMT[Address]HAMT[AllocationID]Allocation - + // Sequence number for allocation IDs. // The value `0` is reserved for "no allocation" NextAllocationId: AllocationID // uint64 @@ -150,7 +150,7 @@ The verified registry provides a new method to process removals, replacing `Rest ``` struct RemoveExpiredAllocationsParams { - Client: Address // client to clean up (need not be the caller) + Client: ActorID // client to clean up (need not be the caller) AllocationIDs: []AllocationID // empty for "all", or specify a set } @@ -190,19 +190,19 @@ data, and corresponding benefit of incentivized storage power. ``` struct Claim { // The provider storing the data (from allocation). - Provider: Address + Provider: ActorID // The client which allocated the DataCap (from allocation). - Client: Address + Client: ActorID // Identifier of the data committed (from allocation). Data: CID // The (padded) size of data (from allocation). Size: uint64 // The minimum period which the provider must commit to storing the piece (from allocation). - TermMinimum: uint64 + TermMinimum: int64 // The maximum period for which the provider can earn QA-power for the piece (from allocation). - TermMaximum: uint64 + TermMaximum: int64 // The epoch at which the (first range of the) piece was committed. - TermStart: uint64 + TermStart: int64 // ID of the provider's sector in which the data is committed. Sector uint64 } @@ -229,7 +229,7 @@ data cap tokens from its balance. ``` struct SectorAllocationClaim { // Client of the allocation being claimed. - Client: Address + Client: ActorID // The allocation being claimed. AllocationID: AllocationID // The piece data committed (either the allocations data, or a part of it). @@ -266,7 +266,7 @@ The record of a claim may be removed after the term maximum has elapsed. ``` struct RemoveExpiredClaimsParams { - Provider: Address // provider to clean up (need not be the caller) + Provider: ActorID // provider to clean up (need not be the caller) ClaimIDs: []ClaimID // empty for "all", or specify a set } @@ -292,7 +292,7 @@ A client of a claim may increase its maximum term up to `MaximumVerifiedAllocati ``` struct ClaimTerm { - Provider: Address // needed to find claim in state + Provider: ActorID // needed to find claim in state ClaimID: ClaimID TermMaximum: int64 // new duration in epochs from TermStart } @@ -379,19 +379,35 @@ The registry rejects the transfer if the sum of sizes does not match the amount // A request to create an allocation with datacap tokens. // Field semantics match the Allocation structure. struct AllocationRequest { - Provider: Address + // The provider (miner actor) which may claim the allocation. + // (Historical note: network version 9 introduced this type with an Address for this field but + // it was switched to an ActorID for network version 10 and later.) + Provider: ActorID + // Identifier of the data to be committed. Data: Cid + // The (padded) size of data. Size: PaddedPieceSize - TermMin: ChainEpoch - TermMax: ChainEpoch - Expiration: ChainEpoch + // The minimum duration which the provider must commit to storing the piece to avoid + // early-termination penalties (epochs). + TermMin: int64 + // The maximum period for which a provider can earn quality-adjusted power + // for the piece (epochs). + TermMax: int64 + // The latest epoch by which a provider must commit data before the allocation expires. + Expiration: int64 } // A request to extend the term of an existing claim with datacap tokens. struct ClaimExtensionRequest { - Provider: Address + // The provider (miner actor) which may claim the allocation. + // (Historical note: network version 9 introduced this type with an Address for this field but + // it was switched to an ActorID for network version 10 and later.) + Provider: ActorID + // Identifier of the claim to be extended. Claim: ClaimID - TermMax: ChainEpoch + // The new maximum period for which a provider can earn quality-adjusted power + // for the piece (epochs). + TermMax: int64 } // Operator-data payload for a datacap token transfer receiver hook. @@ -854,5 +870,15 @@ will then grant maximal per-byte quality-adjusted power for the sector's full li Implementation is in progress on the `decouple-fil+` branch of the built-in actors repository: https://github.com/filecoin-project/builtin-actors/tree/decouple-fil+. +## Historical notes + +This FIP was originally accepted with "Address" in most places where "ActorID" is now used within +the types in this document. However, these were implemented and launched in network version 9 as +ActorID. + +Both `ClaimExtensionRequest` and `AllocationRequest` were originally defined with an `Address` field +for the provider and this remained in the implementation for network version 9. However, this was +changed to `ActorID` for network version 10 and later. + ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From 5d4e6ad39af7bb004e9f9a24062c2ac68b6e3c07 Mon Sep 17 00:00:00 2001 From: Rod Vagg Date: Sat, 16 Mar 2024 10:59:33 +1100 Subject: [PATCH 2/2] FIP-0045: fix network version numbers (9->17, 10->18) --- FIPS/fip-0045.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/FIPS/fip-0045.md b/FIPS/fip-0045.md index c9a7ce3f..66b43e1c 100644 --- a/FIPS/fip-0045.md +++ b/FIPS/fip-0045.md @@ -380,8 +380,8 @@ The registry rejects the transfer if the sum of sizes does not match the amount // Field semantics match the Allocation structure. struct AllocationRequest { // The provider (miner actor) which may claim the allocation. - // (Historical note: network version 9 introduced this type with an Address for this field but - // it was switched to an ActorID for network version 10 and later.) + // (Historical note: network version 17 introduced this type with an Address for this field but + // it was switched to an ActorID for network version 18 and later.) Provider: ActorID // Identifier of the data to be committed. Data: Cid @@ -400,8 +400,8 @@ struct AllocationRequest { // A request to extend the term of an existing claim with datacap tokens. struct ClaimExtensionRequest { // The provider (miner actor) which may claim the allocation. - // (Historical note: network version 9 introduced this type with an Address for this field but - // it was switched to an ActorID for network version 10 and later.) + // (Historical note: network version 17 introduced this type with an Address for this field but + // it was switched to an ActorID for network version 18 and later.) Provider: ActorID // Identifier of the claim to be extended. Claim: ClaimID @@ -873,12 +873,12 @@ https://github.com/filecoin-project/builtin-actors/tree/decouple-fil+. ## Historical notes This FIP was originally accepted with "Address" in most places where "ActorID" is now used within -the types in this document. However, these were implemented and launched in network version 9 as +the types in this document. However, these were implemented and launched in network version 17 as ActorID. Both `ClaimExtensionRequest` and `AllocationRequest` were originally defined with an `Address` field -for the provider and this remained in the implementation for network version 9. However, this was -changed to `ActorID` for network version 10 and later. +for the provider and this remained in the implementation for network version 17. However, this was +changed to `ActorID` for network version 18 and later. ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).