Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rjan90 merged 1 commit into from
Feb 26, 2025
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions api/api_full.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down
8 changes: 4 additions & 4 deletions build/openrpc/full.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
{
Expand Down Expand Up @@ -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": [
{
Expand Down Expand Up @@ -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": [
{
Expand Down Expand Up @@ -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": [
{
Expand Down
8 changes: 8 additions & 0 deletions documentation/en/api-v1-unstable-methods.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down