Documentation
¶
Overview ¶
Package terminate implements routines for previewing the costs of terminating the sectors on the miners owned by an agent
It is possible to preview the cost of terminating a single sector, or all the sectors on a miner.“
Calculation methods ¶
There are two methods that can be used to preview the cost of terminating sector(s):
A slower "on-chain" method can be used that utilizes the `StateCompute` JSON-RPC API to calculate the cost by simulating the execution of the termination messages on a Filecoin node using the system actors.
A faster "off-chain" method can be used that retrieves the sector data and feeds it into calculations that match what the system actors would do.
Sampling for approximate results ¶
It is possible to preview the cost of terminating all the sectors by examining every sector. However, this can be slow, particularly for very large miners. For situations where an speed vs. accuracy trade-off is acceptable, it is also possible to sample a subset of sectors and extrapolate the results for an approximate result.
For example:
f096133 On-chain: 52385/52385 0m12.557s Liquidation Value: 7822.794 @3450134 Recovery Pct: 76.848% f096133 Offchain: 840/52385 0m1.501s Liquidation Value: 7820.798 @3450134 Recovery Pct: 76.829%
Using the "off-chain" method, only 840 sectors were sampled, but the query completed in 1.5 seconds instead of 12.5 seconds, but the approximated result was very close to the "on-chain" method which simulated the termination of every sector using the system actors.
Previewing terminating a single sector on a miner ¶
The PreviewTerminateSector function can be used to preview the termination costs for a single sector on a miner. This function is flexible, and can do either "on-chain" or "off-chain" calculations.
Previewing terminating all sectors on a miner ¶
The PreviewTerminateSectors function can be used preview the termination costs for all the sectors on a miner. This function is flexible, and can do either "on-chain" or "off-chain" calculations. It can terminate all sectors or sample a subset of sectors for an approximate result.
The PreviewTerminateSectorsQuick function is preferred for quick results using opinionated settings, sampling, "off-chain" calcuation, and a simpler API (no channels for streaming progress)
Previewing terminating all sectors on all miners for an agent ¶
The [PreviewAgentTermination] function will preview terminating all the sectors on all the miners for an agent (using sampling and "off-chain" calculation) and will return aggregated stats (AgentCollateralStats).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func PreviewTerminateSectors ¶
func PreviewTerminateSectors( ctx context.Context, api *lotusapi.FullNodeStruct, minerAddr address.Address, tipset string, vmHeight uint64, batchSize uint64, gasLimit uint64, useSampling bool, optimize bool, offchain bool, maxPartitions uint64, errorCh chan error, progressCh chan *PreviewTerminateSectorsProgress, resultCh chan *PreviewTerminateSectorsReturn, )
PreviewTerminateSectors will preview the cost of terminating all the sectors for a miner.
This function is intended to be run as a goroutine. Channels are used to stream back progress and results/errors, so clients can report progress as the query progresses.
- tipset takes a string selector, similar to Lotus, eg. "@1234", or "cid,cid,cid"
- batchSize is the number of sectors to query per message. If set to zero, and gasLimit is also zero, a default batch size will be calculated based on the miner's worker balance.
- offchain controls whether or not to use the "on-chain" or "off-chain" calculation method.
- optimize will make additional queries to try to select deadlines to sample that are evenly distributed over historical time.
- maxPartitions controls how many partitions to sample. If set to zero, all partitions will be sampled.
Use the simpler, more opinionated PreviewTerminateSectorsQuick function for quick results using sampling, "off-chain" calcuation, and a simpler API (no channels for streaming progress)
Types ¶
type AgentCollateralStats ¶
type AgentCollateralStats struct {
AvailableBalance *big.Int `json:"agentAvailableBalance"`
TerminationPenalty *big.Int `json:"terminationPenalty"`
MinersTerminationStats []*MinerCollateralStat `json:"minersCollateralStats"`
Epoch abi.ChainEpoch `json:"epoch"`
}
func (*AgentCollateralStats) Summarize ¶
func (cs *AgentCollateralStats) Summarize() PreviewAgentTerminationSummary
type MinerCollateralStat ¶
type PreviewAgentTerminationSummary ¶
type PreviewAgentTerminationSummary struct {
TerminationPenalty *big.Int
InitialPledge *big.Int
VestingBalance *big.Int
MinersAvailableBal *big.Int
AgentAvailableBal *big.Int
}
func (PreviewAgentTerminationSummary) LTV ¶
func (ats PreviewAgentTerminationSummary) LTV(principal *big.Int) *big.Int
func (PreviewAgentTerminationSummary) LiquidationValue ¶
func (ats PreviewAgentTerminationSummary) LiquidationValue() *big.Int
func (PreviewAgentTerminationSummary) RecoveryRate ¶
func (ats PreviewAgentTerminationSummary) RecoveryRate() *big.Int
1e18 = 100%
type PreviewTerminateSectorsProgress ¶
type PreviewTerminateSectorsProgress struct {
Epoch abi.ChainEpoch
MinerInfo minertypes.MinerInfo
WorkerActor *types.ActorV5
PrevHeightForImmutable abi.ChainEpoch
WorkerActorPrev *types.ActorV5
BatchSize uint64
GasLimit uint64
DeadlinePartitionCount int
DeadlinePartitionIndex int
Deadline uint64
DeadlineImmutable bool
Partition int
SectorsCount uint64
SliceStart uint64
SliceEnd uint64
SliceCount uint64
}
PreviewTerminateSectorsProgress is returned multiple times during a streaming query to report progress.
type PreviewTerminateSectorsReturn ¶
type PreviewTerminateSectorsReturn struct {
Actor *types.ActorV5
MinerInfo minertypes.MinerInfo
VestingBalance *big.Int
InitialPledge *big.Int
SectorStats *SectorStats
SectorsTerminated uint64
SectorsCount uint64
SectorsInSkippedPartitions uint64
Epoch abi.ChainEpoch
PartitionsCount uint64
SampledPartitionsCount uint64
Tipset *types.TipSet
}
PreviewTerminateSectorsReturn contains the aggregated results from a query.
func PreviewTerminateSectorsQuick ¶
func PreviewTerminateSectorsQuick( ctx context.Context, api *lotusapi.FullNodeStruct, minerAddr address.Address, ts *types.TipSet, ) (*PreviewTerminateSectorsReturn, error)
Use the more complex PreviewTerminateSectors function for more control over the number of sectors to sample, or to use the "on-chain" calculation method, and also to stream results.
type SectorStats ¶
type SectorStats struct {
TerminationPenalty *big.Int
SectorFeePenalty *big.Int
Activation *big.Int
MinActivation abi.ChainEpoch
MaxActivation abi.ChainEpoch
Age *big.Int
MinAge abi.ChainEpoch
MaxAge abi.ChainEpoch
Expiration *big.Int
MinExpiration abi.ChainEpoch
MaxExpiration abi.ChainEpoch
DealWeight *big.Int
VerifiedDealWeight *big.Int
InitialPledge *big.Int
ExpectedDayReward *big.Int
ExpectedStoragePledge *big.Int
PowerBaseEpoch *big.Int
MinPowerBaseEpoch abi.ChainEpoch
MaxPowerBaseEpoch abi.ChainEpoch
ReplacedDayReward *big.Int
SectorCount int64
}
func NewSectorStats ¶
func NewSectorStats() *SectorStats
func PreviewTerminateSector ¶
func PreviewTerminateSector( ctx context.Context, api *lotusapi.FullNodeStruct, minerAddr address.Address, tipset string, vmHeight uint64, sectorNumber uint64, gasLimit uint64, offchain bool, ) (actor *types.ActorV5, sectorStats *SectorStats, epoch abi.ChainEpoch, err error)
PreviewTerminateSector will preview the cost of terminating a single sector on a miner.
- tipset takes a string selector, similar to Lotus, eg. "@1234", or "cid,cid,cid"
- offchain controls whether or not to use the "on-chain" or "off-chain" calculation method.
func (*SectorStats) Accumulate ¶
func (st *SectorStats) Accumulate(addStats *SectorStats) *SectorStats
func (*SectorStats) AddSector ¶
func (st *SectorStats) AddSector( s *miner.SectorOnChainInfo, height abi.ChainEpoch, termFee *big.Int, sectorFeePenalty *big.Int, ) *SectorStats
func (*SectorStats) ScaleUp ¶
func (st *SectorStats) ScaleUp(sectorsCount int64, sampledSectorsCount int64) *SectorStats
Source Files