diff --git a/FIPS/fip-0076.md b/FIPS/fip-0076.md index df52bbaa..49c0d35a 100644 --- a/FIPS/fip-0076.md +++ b/FIPS/fip-0076.md @@ -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` 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` 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),