docs(api): document 10% overestimation in collateral/pledge APIs (#12922)

docs(api): document 10% overestimation in collateral/pledge APIs

Author: rjan90

api/api_full.go

@@ -439,20 +439,26 @@ type FullNode interface {
 	// StateMinerRecoveries returns a bitfield indicating the recovering sectors of the given miner
 	StateMinerRecoveries(context.Context, address.Address, types.TipSetKey) (bitfield.BitField, error) //perm:read
 	// StateMinerPreCommitDepositForPower returns the precommit deposit for the specified miner's sector
+	// Note: The value returned is overestimated by 10% (multiplied by 110/100).
+	// See: node/impl/full/state.go StateMinerPreCommitDepositForPower implementation.
 	StateMinerPreCommitDepositForPower(context.Context, address.Address, miner.SectorPreCommitInfo, types.TipSetKey) (types.BigInt, error) //perm:read
 	// 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.
+	// Note: The value returned is overestimated by 10% (multiplied by 110/100).
+	// See: node/impl/full/state.go StateMinerInitialPledgeCollateral implementation.
 	//
 	// 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. This calculation
 	// depends on current network conditions (total power, total pledge and current rewards) at the
 	// given tipset.
+	// Note: The value returned is overestimated by 10% (multiplied by 110/100).
+	// See: node/impl/full/state.go StateMinerInitialPledgeForSector implementation.
 	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
@@ -600,6 +606,8 @@ type FullNode interface {
 	StateVerifiedRegistryRootKey(ctx context.Context, tsk types.TipSetKey) (address.Address, error) //perm:read
 	// StateDealProviderCollateralBounds returns the min and max collateral a storage provider
 	// can issue. It takes the deal size and verified status as parameters.
+	// Note: The min value returned is overestimated by 10% (multiplied by 110/100).
+	// See: node/impl/full/state.go StateDealProviderCollateralBounds implementation.
 	StateDealProviderCollateralBounds(context.Context, abi.PaddedPieceSize, bool, types.TipSetKey) (DealCollateralBounds, error) //perm:read
 
 	// StateCirculatingSupply returns the exact circulating supply of Filecoin at the given tipset.

build/openrpc/full.json

@@ -18656,7 +18656,7 @@
         {
             "name": "Filecoin.StateDealProviderCollateralBounds",
             "description": "```go\nfunc (s *FullNodeStruct) StateDealProviderCollateralBounds(p0 context.Context, p1 abi.PaddedPieceSize, p2 bool, p3 types.TipSetKey) (DealCollateralBounds, error) {\n\tif s.Internal.StateDealProviderCollateralBounds == nil {\n\t\treturn *new(DealCollateralBounds), ErrNotSupported\n\t}\n\treturn s.Internal.StateDealProviderCollateralBounds(p0, p1, p2, p3)\n}\n```",
-            "summary": "StateDealProviderCollateralBounds returns the min and max collateral a storage provider\ncan issue. It takes the deal size and verified status as parameters.\n",
+            "summary": "StateDealProviderCollateralBounds returns the min and max collateral a storage provider\ncan issue. It takes the deal size and verified status as parameters.\nNote: The min value returned is overestimated by 10% (multiplied by 110/100).\nSee: node/impl/full/state.go StateDealProviderCollateralBounds implementation.\n",
             "paramStructure": "by-position",
             "params": [
                 {
@@ -22086,7 +22086,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 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",
+            "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.\nNote: The value returned is overestimated by 10% (multiplied by 110/100).\nSee: node/impl/full/state.go StateMinerInitialPledgeCollateral implementation.\n\nDeprecated: Use StateMinerInitialPledgeForSector instead.\n",
             "paramStructure": "by-position",
             "params": [
                 {
@@ -22218,7 +22218,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\nduration, size, and combined size of any verified pieces within the sector. This calculation\ndepends on current network conditions (total power, total pledge and current rewards) at the\ngiven tipset.\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 (total power, total pledge and current rewards) at the\ngiven tipset.\nNote: The value returned is overestimated by 10% (multiplied by 110/100).\nSee: node/impl/full/state.go StateMinerInitialPledgeForSector implementation.\n",
             "paramStructure": "by-position",
             "params": [
                 {
@@ -22569,7 +22569,7 @@
         {
             "name": "Filecoin.StateMinerPreCommitDepositForPower",
             "description": "```go\nfunc (s *FullNodeStruct) StateMinerPreCommitDepositForPower(p0 context.Context, p1 address.Address, p2 miner.SectorPreCommitInfo, p3 types.TipSetKey) (types.BigInt, error) {\n\tif s.Internal.StateMinerPreCommitDepositForPower == nil {\n\t\treturn *new(types.BigInt), ErrNotSupported\n\t}\n\treturn s.Internal.StateMinerPreCommitDepositForPower(p0, p1, p2, p3)\n}\n```",
-            "summary": "StateMinerPreCommitDepositForPower returns the precommit deposit for the specified miner's sector\n",
+            "summary": "StateMinerPreCommitDepositForPower returns the precommit deposit for the specified miner's sector\nNote: The value returned is overestimated by 10% (multiplied by 110/100).\nSee: node/impl/full/state.go StateMinerPreCommitDepositForPower implementation.\n",
             "paramStructure": "by-position",
             "params": [
                 {

documentation/en/api-v1-unstable-methods.md

@@ -6430,6 +6430,8 @@ Response:
 ### StateDealProviderCollateralBounds
 StateDealProviderCollateralBounds returns the min and max collateral a storage provider
 can issue. It takes the deal size and verified status as parameters.
+Note: The min value returned is overestimated by 10% (multiplied by 110/100).
+See: node/impl/full/state.go StateDealProviderCollateralBounds implementation.
 
 
 Perms: read
@@ -7476,6 +7478,8 @@ deal space in the sector in order to perform a QAP calculation. Since network ve
 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.
+Note: The value returned is overestimated by 10% (multiplied by 110/100).
+See: node/impl/full/state.go StateMinerInitialPledgeCollateral implementation.
 
 Deprecated: Use StateMinerInitialPledgeForSector instead.
 
@@ -7519,6 +7523,8 @@ StateMinerInitialPledgeForSector returns the initial pledge collateral for a giv
 duration, size, and combined size of any verified pieces within the sector. This calculation
 depends on current network conditions (total power, total pledge and current rewards) at the
 given tipset.
+Note: The value returned is overestimated by 10% (multiplied by 110/100).
+See: node/impl/full/state.go StateMinerInitialPledgeForSector implementation.
 
 
 Perms: read
@@ -7630,6 +7636,8 @@ Response:
 
 ### StateMinerPreCommitDepositForPower
 StateMinerPreCommitDepositForPower returns the precommit deposit for the specified miner's sector
+Note: The value returned is overestimated by 10% (multiplied by 110/100).
+See: node/impl/full/state.go StateMinerPreCommitDepositForPower implementation.
 
 
 Perms: read