Skip to content

Commit b88cede

Browse files
authored
Expand documentation for deal activation and verified claim parameters and results. (#1325)
1 parent 211698a commit b88cede

File tree

4 files changed

+18
-10
lines changed

4 files changed

+18
-10
lines changed

actors/market/src/lib.rs

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -530,9 +530,10 @@ impl Actor {
530530
Ok(VerifyDealsForActivationReturn { sectors: sectors_data })
531531
}
532532

533-
/// Activate a set of deals, returning the deal space and extra info for sectors containing
534-
/// verified deals. Sectors are activated in parameter-defined order and can fail independently of
535-
/// each other with the responsible ExitCode recorded in a BatchReturn.
533+
/// Activate a set of deals grouped by sector, returning the size and
534+
/// extra info about verified deals.
535+
/// Sectors' deals are activated in parameter-defined order.
536+
/// Each sector's deals are activated or fail as a group, but independently of other sectors.
536537
fn batch_activate_deals(
537538
rt: &impl Runtime,
538539
params: BatchActivateDealsParams,

actors/market/src/types.rs

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -71,11 +71,9 @@ pub struct PublishStorageDealsReturn {
7171
pub valid_deals: BitField,
7272
}
7373

74-
// Changed since V2:
75-
// - Array of Sectors rather than just one
76-
// - Removed SectorStart
7774
#[derive(Serialize_tuple, Deserialize_tuple, Debug, Clone, Eq, PartialEq)]
7875
pub struct VerifyDealsForActivationParams {
76+
/// Deals to verify, grouped by sector.
7977
pub sectors: Vec<SectorDeals>,
8078
}
8179

@@ -100,9 +98,11 @@ pub struct SectorDealData {
10098
#[derive(Serialize_tuple, Deserialize_tuple, Debug, Clone, Eq, PartialEq)]
10199
#[serde(transparent)]
102100
pub struct BatchActivateDealsParams {
101+
/// Deals to activate, grouped by sector.
103102
pub sectors: Vec<SectorDeals>,
104103
}
105104

105+
// Information about a verified deal that has been activated.
106106
#[derive(Serialize_tuple, Deserialize_tuple, Debug, Clone, Eq, PartialEq)]
107107
pub struct VerifiedDealInfo {
108108
pub client: ActorID,
@@ -111,16 +111,21 @@ pub struct VerifiedDealInfo {
111111
pub size: PaddedPieceSize,
112112
}
113113

114+
// Information about a sector-grouping of deals that have been activated.
114115
#[derive(Serialize_tuple, Deserialize_tuple, Debug, Clone, Eq, PartialEq)]
115116
pub struct DealActivation {
117+
/// The total size of the non-verified deals activated.
116118
#[serde(with = "bigint_ser")]
117119
pub nonverified_deal_space: BigInt,
120+
/// Information about each verified deal activated.
118121
pub verified_infos: Vec<VerifiedDealInfo>,
119122
}
120123

121124
#[derive(Serialize_tuple, Deserialize_tuple, Debug, Clone, Eq, PartialEq)]
122125
pub struct BatchActivateDealsResult {
126+
/// Status of each sector grouping of deals.
123127
pub activation_results: BatchReturn,
128+
/// Activation information for the sector groups that were activated.
124129
pub activations: Vec<DealActivation>,
125130
}
126131

actors/verifreg/src/lib.rs

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -366,10 +366,9 @@ impl Actor {
366366
/// Called by storage provider actor to claim allocations for data provably committed to storage.
367367
/// For each allocation claim, the registry checks that the provided piece CID
368368
/// and size match that of the allocation.
369-
/// Returns a vec of claimed spaces parallel (with same length and corresponding indices) to
370-
/// the requested allocations. When `all_or_nothing` is false, failed claims are represented by
371-
/// DataCap::zero() entry in the result vec. When `all_or_nothing` is enabled, any failure to
372-
/// claim results in the entire function returning an error.
369+
/// Returns an indicator of success for each claim, and the size of each successful claim.
370+
/// When `all_or_nothing` is enabled, any failure to claim results in the entire
371+
/// method returning an error.
373372
pub fn claim_allocations(
374373
rt: &impl Runtime,
375374
params: ClaimAllocationsParams,

actors/verifreg/src/types.rs

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,7 @@ pub struct SectorAllocationClaim {
133133
#[derive(Clone, Debug, PartialEq, Eq, Serialize_tuple, Deserialize_tuple)]
134134
pub struct ClaimAllocationsParams {
135135
pub allocations: Vec<SectorAllocationClaim>,
136+
// Whether to abort entirely if any claim fails.
136137
pub all_or_nothing: bool,
137138
}
138139

@@ -145,7 +146,9 @@ pub struct SectorAllocationClaimResult {
145146

146147
#[derive(Clone, Debug, PartialEq, Eq, Serialize_tuple, Deserialize_tuple)]
147148
pub struct ClaimAllocationsReturn {
149+
// Success/failure indication for each claim.
148150
pub claim_results: BatchReturn,
151+
// The claimed space for each successful claim, in order.
149152
pub claims: Vec<SectorAllocationClaimResult>,
150153
}
151154

0 commit comments

Comments
 (0)