doc(miner): more docs about pledge calculation delta

filecoin-project · Sep 19, 2024 · 955ea3e · 955ea3e
1 parent d0b3b57
commit 955ea3e
Show file tree

Hide file tree

Showing 4 changed files with 28 additions and 10 deletions.
diff --git a/api/api_full.go b/api/api_full.go
@@ -408,11 +408,18 @@ type FullNode interface {
 	StateMinerRecoveries(context.Context, address.Address, types.TipSetKey) (bitfield.BitField, error) //perm:read
 	// StateMinerPreCommitDepositForPower returns the precommit deposit for the specified miner's sector
 	StateMinerPreCommitDepositForPower(context.Context, address.Address, miner.SectorPreCommitInfo, types.TipSetKey) (types.BigInt, error) //perm:read
-	// StateMinerInitialPledgeCollateral returns the initial pledge collateral for the specified miner's sector
+	// StateMinerInitialPledgeCollateral attempts to calculate the initial pledge collateral based on a SectorPreCommitInfo.
+	// This method uses the DealIDs field in SectorPreCommitInfo to determine the amount of verified
+	// deal space in the sector in order to perform a QAP calculation. Since network version 22 and
+	// the introduction of DDO, the DealIDs field can no longer be used to reliably determine verified
+	// deal space; therefore, this method is deprecated. Use StateMinerInitialPledgeForSector instead
+	// and pass in the verified deal space directly.
 	//
-	// Deprecated: Use StateMinerInitialPledgeForSector instead
+	// Deprecated: Use StateMinerInitialPledgeForSector instead.
 	StateMinerInitialPledgeCollateral(context.Context, address.Address, miner.SectorPreCommitInfo, types.TipSetKey) (types.BigInt, error) //perm:read
-	// StateMinerInitialPledgeForSector returns the initial pledge collateral for a given sector duration, size and combined size of any verified pieces within the sector
+	// StateMinerInitialPledgeForSector returns the initial pledge collateral for a given sector
+	// duration, size, and combined size of any verified pieces within the sector. This calculation
+	// depends on current network conditions at the given tipset.
 	StateMinerInitialPledgeForSector(ctx context.Context, sectorDuration abi.ChainEpoch, sectorSize abi.SectorSize, verifiedSize uint64, tsk types.TipSetKey) (types.BigInt, error) //perm:read
 	// StateMinerAvailableBalance returns the portion of a miner's balance that can be withdrawn or spent
 	StateMinerAvailableBalance(context.Context, address.Address, types.TipSetKey) (types.BigInt, error) //perm:read

diff --git a/build/openrpc/full.json b/build/openrpc/full.json
@@ -20865,7 +20865,7 @@
         {
             "name": "Filecoin.StateMinerInitialPledgeCollateral",
             "description": "```go\nfunc (s *FullNodeStruct) StateMinerInitialPledgeCollateral(p0 context.Context, p1 address.Address, p2 miner.SectorPreCommitInfo, p3 types.TipSetKey) (types.BigInt, error) {\n\tif s.Internal.StateMinerInitialPledgeCollateral == nil {\n\t\treturn *new(types.BigInt), ErrNotSupported\n\t}\n\treturn s.Internal.StateMinerInitialPledgeCollateral(p0, p1, p2, p3)\n}\n```",
-            "summary": "StateMinerInitialPledgeCollateral returns the initial pledge collateral for the specified miner's sector\n\nDeprecated: Use StateMinerInitialPledgeForSector instead\n",
+            "summary": "StateMinerInitialPledgeCollateral attempts to calculate the initial pledge collateral based on a SectorPreCommitInfo.\nThis method uses the DealIDs field in SectorPreCommitInfo to determine the amount of verified\ndeal space in the sector in order to perform a QAP calculation. Since network version 22 and\nthe introduction of DDO, the DealIDs field can no longer be used to reliably determine verified\ndeal space; therefore, this method is deprecated. Use StateMinerInitialPledgeForSector instead\nand pass in the verified deal space directly.\n\nDeprecated: Use StateMinerInitialPledgeForSector instead.\n",
             "paramStructure": "by-position",
             "params": [
                 {
@@ -20997,7 +20997,7 @@
         {
             "name": "Filecoin.StateMinerInitialPledgeForSector",
             "description": "```go\nfunc (s *FullNodeStruct) StateMinerInitialPledgeForSector(p0 context.Context, p1 abi.ChainEpoch, p2 abi.SectorSize, p3 uint64, p4 types.TipSetKey) (types.BigInt, error) {\n\tif s.Internal.StateMinerInitialPledgeForSector == nil {\n\t\treturn *new(types.BigInt), ErrNotSupported\n\t}\n\treturn s.Internal.StateMinerInitialPledgeForSector(p0, p1, p2, p3, p4)\n}\n```",
-            "summary": "StateMinerInitialPledgeForSector returns the initial pledge collateral for a given sector duration, size and combined size of any verified pieces within the sector\n",
+            "summary": "StateMinerInitialPledgeForSector returns the initial pledge collateral for a given sector\nduration, size, and combined size of any verified pieces within the sector. This calculation\ndepends on current network conditions at the given tipset.\n",
             "paramStructure": "by-position",
             "params": [
                 {

diff --git a/documentation/en/api-v1-unstable-methods.md b/documentation/en/api-v1-unstable-methods.md
@@ -7105,9 +7105,14 @@ Response:
 ```
 
 ### StateMinerInitialPledgeCollateral
-StateMinerInitialPledgeCollateral returns the initial pledge collateral for the specified miner's sector
+StateMinerInitialPledgeCollateral attempts to calculate the initial pledge collateral based on a SectorPreCommitInfo.
+This method uses the DealIDs field in SectorPreCommitInfo to determine the amount of verified
+deal space in the sector in order to perform a QAP calculation. Since network version 22 and
+the introduction of DDO, the DealIDs field can no longer be used to reliably determine verified
+deal space; therefore, this method is deprecated. Use StateMinerInitialPledgeForSector instead
+and pass in the verified deal space directly.
 
-Deprecated: Use StateMinerInitialPledgeForSector instead
+Deprecated: Use StateMinerInitialPledgeForSector instead.
 
 
 Perms: read
@@ -7145,7 +7150,9 @@ Inputs:
 Response: `"0"`
 
 ### StateMinerInitialPledgeForSector
-StateMinerInitialPledgeForSector returns the initial pledge collateral for a given sector duration, size and combined size of any verified pieces within the sector
+StateMinerInitialPledgeForSector returns the initial pledge collateral for a given sector
+duration, size, and combined size of any verified pieces within the sector. This calculation
+depends on current network conditions at the given tipset.
 
 
 Perms: read

diff --git a/itests/sector_miner_collateral_test.go b/itests/sector_miner_collateral_test.go
@@ -167,8 +167,12 @@ func TestMinerBalanceCollateral(t *testing.T) {
 
 // TestPledgeCalculations tests the pledge calculations for sectors with different piece combinations
 // and verified deals.
-// We first verify that the deprecated pledge calculation that uses PreCommit with Deal information
-// matches the new one that just uses sector size, duration and a simple verified size.
+// We first verify that the deprecated pledge calculation (StateMinerInitialPledgeCollateral) that
+// uses PreCommit with Deal information matches the new one (StateMinerInitialPledgeForSector) that
+// just uses sector size, duration and a simple verified size. Post-DDO, we no longer use or need
+// the DealIDs field in SectorPreCommitInfo, so the deprecated calculation method can't rely on it
+// to determine verified size. In this test, we intentionally build DealIDs so the deprecated method
+// still works as expected.
 // Then we compare the pledge calculations for sectors with different piece combinations and
 // verified deals according to expected rules about verified pieces requiring 10x pledge.
 // Most of the complication in this test is for setting up verified deals and allocations so we can