diff --git a/FIPS/fip-0076.md b/FIPS/fip-0076.md index df52bbaa..bdef7d16 100644 --- a/FIPS/fip-0076.md +++ b/FIPS/fip-0076.md @@ -307,7 +307,7 @@ type ProveReplicaUpdates2Return = ProveCommit2Return; When a piece manifest specifies one or notification receivers, the storage miner invokes these receivers after activating the sector or replica update. -The receiving actor must accept the `SectorContentChanged` method number and parameter schema. +The receiving actor must accept the `SectorContentChanged` method number (2034386435) and parameter schema. `SectorContentChanged` is an FRC-0046 method, intended to be implemented by user-programmed actors. The miner actor will invoke each receiver address only once, with a batch of notification payloads. @@ -561,6 +561,63 @@ struct GetDealSectorReturn { } ``` +### Verified registry actor + +The built-in verified registry actor exports FRC-0042 methods to iterate all allocations and claims. +`ListAllocations` (method 241218346) returns all allocation IDs up to some caller-specified limit, +and an opaque cursor which can be used to continue the listing where the first response left off. +`ListClaims` (method 3587470581) similarly returns all claim IDs up to some limit, and a cursor for continuation. +The order of iteration is undefined to the caller, and will match the internal HAMT structure's ordering. +A cursor is tied to the actor state from which it was generated. +Clients can only assume a cursor is valid for use immediately after it is returned. + +``` +// Exported API +struct ListAllocationsParams { + Cursor: RawBytes, + Limit: u64, +} + +struct AllocationKey { + Client: ActorID, + ID: AllocationID, +} + +struct ListAllocationsResponse { + Allocations: Vec, + NextCursor: Option, +} + +struct ListClaimsParams { + Cursor: RawBytes, + Limit: u64, +} + +struct ClaimKey { + Provider: ActorID, + ID: ClaimID, +} + +struct ListClaimsResponse { + Claims: Vec, + NextCursor: Option, +} +``` + +A cursor is a serialized representation of the HAMT root CID, the next client/provider ID, +and the next allocation/claim ID for that client/provider. +A cursor is rejected with `USR_ILLEGAL_ARGUMENT` if the HAMT root does not match the verified registry state, +or the IDs do not exist. + +``` +// Internal structure +struct Cursor { + Root: Cid, + OuterKey: ActorID, + InnerKey: u64, // Allocation or claim ID +} + +``` ### Migration The built-in market actor's `ProviderSectors` mapping is initialised from the existing deal state @@ -641,6 +698,12 @@ as a side effect of publishing a deal. The reason for this change is that verified allocations and deals are independent: a client can allocate DataCap without necessarily involving the built-in market actor, and save the SP significant gas costs by doing so. +### Verified registry iteration APIs + +The methods to list allocations and claims provide simpler accessibility of these structures, +since in many cases they may be the only on-chain representation of a "deal". +The methods are primarily intended to be invoked from off-chain, replacing direct state inspection. + ## Backwards Compatibility This proposal deprecated the miner methods `PreCommitSector` (method 6), `PreCommitSectorBatch` (method 25), @@ -827,6 +890,7 @@ This proposal makes that behaviour cheaper by not storing the meaningless metada Implementation of the protocol changes is being developed in the `integration/direct-onboarding` [branch of the built-in actors](https://github.com/filecoin-project/builtin-actors/tree/integration/direct-onboarding) repository. +The new verified registry methods are implemented in https://github.com/filecoin-project/builtin-actors/pull/1468. ## Copyright