From a26712ebc459bf5ea4ba9c2328ee305655f9bac3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Magiera?= Date: Fri, 23 Jul 2021 15:40:30 +0200 Subject: [PATCH] config: Bring some docs from filecoin-docs --- node/config/doc_gen.go | 75 ++++++++++++++++++++++------------- node/config/types.go | 88 ++++++++++++++++++++++++++++++++---------- 2 files changed, 115 insertions(+), 48 deletions(-) diff --git a/node/config/doc_gen.go b/node/config/doc_gen.go index 104984a64..ea68dc344 100644 --- a/node/config/doc_gen.go +++ b/node/config/doc_gen.go @@ -34,7 +34,8 @@ var Doc = map[string][]DocField{ Name: "DisableMetadataLog", Type: "bool", - Comment: ``, + Comment: `Note that in case of metadata corruption it might be much harder to recover +your node if metadata log is disabled`, }, }, "BatchFeeConfig": []DocField{ @@ -94,7 +95,8 @@ var Doc = map[string][]DocField{ Name: "SimultaneousTransfers", Type: "uint64", - Comment: ``, + Comment: `The maximum number of simultaneous data transfers between the client +and storage providers`, }, }, "Common": []DocField{ @@ -128,49 +130,51 @@ var Doc = map[string][]DocField{ Name: "ConsiderOnlineStorageDeals", Type: "bool", - Comment: ``, + Comment: `When enabled, the miner can accept online deals`, }, { Name: "ConsiderOfflineStorageDeals", Type: "bool", - Comment: ``, + Comment: `When enabled, the miner can accept offline deals`, }, { Name: "ConsiderOnlineRetrievalDeals", Type: "bool", - Comment: ``, + Comment: `When enabled, the miner can accept retrieval deals`, }, { Name: "ConsiderOfflineRetrievalDeals", Type: "bool", - Comment: ``, + Comment: `When enabled, the miner can accept offline retrieval deals`, }, { Name: "ConsiderVerifiedStorageDeals", Type: "bool", - Comment: ``, + Comment: `When enabled, the miner can accept verified deals`, }, { Name: "ConsiderUnverifiedStorageDeals", Type: "bool", - Comment: ``, + Comment: `When enabled, the miner can accept unverified deals`, }, { Name: "PieceCidBlocklist", Type: "[]cid.Cid", - Comment: ``, + Comment: `A list of Data CIDs to reject when making deals`, }, { Name: "ExpectedSealDuration", Type: "Duration", - Comment: ``, + Comment: `Maximum expected amount of time getting the deal into a sealed sector will take +This includes the time the deal will need to get transferred and published +before being assigned to a sector`, }, { Name: "MaxDealStartDelay", @@ -182,8 +186,8 @@ var Doc = map[string][]DocField{ Name: "PublishMsgPeriod", Type: "Duration", - Comment: `The amount of time to wait for more deals to arrive before -publishing`, + Comment: `When a deal is ready to publish, the amount of time to wait for more +deals to be ready to publish before publishing them all as a batch`, }, { Name: "MaxDealsPerPublishMsg", @@ -209,13 +213,15 @@ as a multiplier of the minimum collateral bound`, Name: "Filter", Type: "string", - Comment: ``, + Comment: `A command used for fine-grained evaluation of storage deals +see https://docs.filecoin.io/mine/lotus/miner-configuration/#using-filters-for-fine-grained-storage-and-retrieval-deal-acceptance for more details`, }, { Name: "RetrievalFilter", Type: "string", - Comment: ``, + Comment: `A command used for fine-grained evaluation of retrieval deals +see https://docs.filecoin.io/mine/lotus/miner-configuration/#using-filters-for-fine-grained-storage-and-retrieval-deal-acceptance for more details`, }, { Name: "RetrievalPricing", @@ -269,19 +275,23 @@ as a multiplier of the minimum collateral bound`, Name: "ListenAddresses", Type: "[]string", - Comment: ``, + Comment: `Binding address for the libp2p host - 0 means random port. +Format: multiaddress; see https://multiformats.io/multiaddr/`, }, { Name: "AnnounceAddresses", Type: "[]string", - Comment: ``, + Comment: `Addresses to explicitally announce to other peers. If not specified, +all interface addresses are announced +Format: multiaddress`, }, { Name: "NoAnnounceAddresses", Type: "[]string", - Comment: ``, + Comment: `Addresses to not announce +Format: multiaddress`, }, { Name: "BootstrapPeers", @@ -333,13 +343,13 @@ as a multiplier of the minimum collateral bound`, Name: "PreCommitControl", Type: "[]string", - Comment: ``, + Comment: `Addresses to send PreCommit messages from`, }, { Name: "CommitControl", Type: "[]string", - Comment: ``, + Comment: `Addresses to send Commit messages from`, }, { Name: "TerminateControl", @@ -405,7 +415,7 @@ over the worker address if this flag is set.`, Name: "MaxWindowPoStGasFee", Type: "types.FIL", - Comment: ``, + Comment: `WindowPoSt is a high-value operation, so the default fee should be high.`, }, { Name: "MaxPublishDealsFee", @@ -463,13 +473,18 @@ over the worker address if this flag is set.`, Name: "Bootstrapper", Type: "bool", - Comment: ``, + Comment: `Run the node in bootstrap-node mode`, }, { Name: "DirectPeers", Type: "[]string", - Comment: ``, + Comment: `DirectPeers specifies peers with direct peering agreements. These peers are +connected outside of the mesh, with all (valid) message unconditionally +forwarded to them. The router will maintain open connections to these peers. +Note that the peering agreement should be reciprocal with direct peers +symmetrically configured at both ends. +Type: Array of multiaddress peerinfo strings, must include peerid (/p2p/12D3K...`, }, { Name: "IPColocationWhitelist", @@ -529,31 +544,37 @@ This parameter is ONLY applicable if the retrieval pricing policy strategy has b Name: "MaxWaitDealsSectors", Type: "uint64", - Comment: `0 = no limit`, + Comment: `Upper bound on how many sectors can be waiting for more deals to be packed in it before it begins sealing at any given time. +If the miner is accepting multiple deals in parallel, up to MaxWaitDealsSectors of new sectors will be created. +If more than MaxWaitDealsSectors deals are accepted in parallel, only MaxWaitDealsSectors deals will be processed in parallel +Note that setting this number too high in relation to deal ingestion rate may result in poor sector packing efficiency +0 = no limit`, }, { Name: "MaxSealingSectors", Type: "uint64", - Comment: `includes failed, 0 = no limit`, + Comment: `Upper bound on how many sectors can be sealing at the same time when creating new CC sectors (0 = unlimited)`, }, { Name: "MaxSealingSectorsForDeals", Type: "uint64", - Comment: `includes failed, 0 = no limit`, + Comment: `Upper bound on how many sectors can be sealing at the same time when creating new sectors with deals (0 = unlimited)`, }, { Name: "WaitDealsDelay", Type: "Duration", - Comment: ``, + Comment: `Period of time that a newly created sector will wait for more deals to be packed in to before it starts to seal. +Sectors which are fully filled will start sealing immediately`, }, { Name: "AlwaysKeepUnsealedCopy", Type: "bool", - Comment: ``, + Comment: `Whether to keep unsealed copies of deal data regardless of whether the client requested that. This lets the miner +avoid the relatively high cost of unsealing the data later, at the cost of more storage space`, }, { Name: "FinalizeEarly", diff --git a/node/config/types.go b/node/config/types.go index 84a631962..5cb76b9ea 100644 --- a/node/config/types.go +++ b/node/config/types.go @@ -30,6 +30,11 @@ type FullNode struct { // // Common type Backup struct { + // When set to true disables metadata log (.lotus/kvlog). This can save disk + // space by reducing metadata redundancy. + // + // Note that in case of metadata corruption it might be much harder to recover + // your node if metadata log is disabled DisableMetadataLog bool } @@ -56,18 +61,28 @@ type MinerSubsystemConfig struct { } type DealmakingConfig struct { - ConsiderOnlineStorageDeals bool - ConsiderOfflineStorageDeals bool - ConsiderOnlineRetrievalDeals bool - ConsiderOfflineRetrievalDeals bool - ConsiderVerifiedStorageDeals bool + // When enabled, the miner can accept online deals + ConsiderOnlineStorageDeals bool + // When enabled, the miner can accept offline deals + ConsiderOfflineStorageDeals bool + // When enabled, the miner can accept retrieval deals + ConsiderOnlineRetrievalDeals bool + // When enabled, the miner can accept offline retrieval deals + ConsiderOfflineRetrievalDeals bool + // When enabled, the miner can accept verified deals + ConsiderVerifiedStorageDeals bool + // When enabled, the miner can accept unverified deals ConsiderUnverifiedStorageDeals bool - PieceCidBlocklist []cid.Cid - ExpectedSealDuration Duration + // A list of Data CIDs to reject when making deals + PieceCidBlocklist []cid.Cid + // Maximum expected amount of time getting the deal into a sealed sector will take + // This includes the time the deal will need to get transferred and published + // before being assigned to a sector + ExpectedSealDuration Duration // Maximum amount of time proposed deal StartEpoch can be in future MaxDealStartDelay Duration - // The amount of time to wait for more deals to arrive before - // publishing + // When a deal is ready to publish, the amount of time to wait for more + // deals to be ready to publish before publishing them all as a batch PublishMsgPeriod Duration // The maximum number of deals to include in a single PublishStorageDeals // message @@ -79,7 +94,11 @@ type DealmakingConfig struct { // The maximum number of parallel online data transfers (storage+retrieval) SimultaneousTransfers uint64 - Filter string + // A command used for fine-grained evaluation of storage deals + // see https://docs.filecoin.io/mine/lotus/miner-configuration/#using-filters-for-fine-grained-storage-and-retrieval-deal-acceptance for more details + Filter string + // A command used for fine-grained evaluation of retrieval deals + // see https://docs.filecoin.io/mine/lotus/miner-configuration/#using-filters-for-fine-grained-storage-and-retrieval-deal-acceptance for more details RetrievalFilter string RetrievalPricing *RetrievalPricing @@ -107,17 +126,25 @@ type RetrievalPricingDefault struct { } type SealingConfig struct { + // Upper bound on how many sectors can be waiting for more deals to be packed in it before it begins sealing at any given time. + // If the miner is accepting multiple deals in parallel, up to MaxWaitDealsSectors of new sectors will be created. + // If more than MaxWaitDealsSectors deals are accepted in parallel, only MaxWaitDealsSectors deals will be processed in parallel + // Note that setting this number too high in relation to deal ingestion rate may result in poor sector packing efficiency // 0 = no limit MaxWaitDealsSectors uint64 - // includes failed, 0 = no limit + // Upper bound on how many sectors can be sealing at the same time when creating new CC sectors (0 = unlimited) MaxSealingSectors uint64 - // includes failed, 0 = no limit + // Upper bound on how many sectors can be sealing at the same time when creating new sectors with deals (0 = unlimited) MaxSealingSectorsForDeals uint64 + // Period of time that a newly created sector will wait for more deals to be packed in to before it starts to seal. + // Sectors which are fully filled will start sealing immediately WaitDealsDelay Duration + // Whether to keep unsealed copies of deal data regardless of whether the client requested that. This lets the miner + // avoid the relatively high cost of unsealing the data later, at the cost of more storage space AlwaysKeepUnsealedCopy bool // Run sector finalization before submitting sector proof to the chain @@ -176,14 +203,17 @@ type MinerFeeConfig struct { MaxPreCommitBatchGasFee BatchFeeConfig MaxCommitBatchGasFee BatchFeeConfig - MaxTerminateGasFee types.FIL + MaxTerminateGasFee types.FIL + // WindowPoSt is a high-value operation, so the default fee should be high. MaxWindowPoStGasFee types.FIL MaxPublishDealsFee types.FIL MaxMarketBalanceAddFee types.FIL } type MinerAddressConfig struct { - PreCommitControl []string + // Addresses to send PreCommit messages from + PreCommitControl []string + // Addresses to send Commit messages from CommitControl []string TerminateControl []string DealPublishControl []string @@ -208,8 +238,15 @@ type API struct { // Libp2p contains configs for libp2p type Libp2p struct { - ListenAddresses []string - AnnounceAddresses []string + // Binding address for the libp2p host - 0 means random port. + // Format: multiaddress; see https://multiformats.io/multiaddr/ + ListenAddresses []string + // Addresses to explicitally announce to other peers. If not specified, + // all interface addresses are announced + // Format: multiaddress + AnnounceAddresses []string + // Addresses to not announce + // Format: multiaddress NoAnnounceAddresses []string BootstrapPeers []string ProtectedPeers []string @@ -220,7 +257,14 @@ type Libp2p struct { } type Pubsub struct { - Bootstrapper bool + // Run the node in bootstrap-node mode + Bootstrapper bool + // DirectPeers specifies peers with direct peering agreements. These peers are + // connected outside of the mesh, with all (valid) message unconditionally + // forwarded to them. The router will maintain open connections to these peers. + // Note that the peering agreement should be reciprocal with direct peers + // symmetrically configured at both ends. + // Type: Array of multiaddress peerinfo strings, must include peerid (/p2p/12D3K... DirectPeers []string IPColocationWhitelist []string RemoteTracer string @@ -247,10 +291,12 @@ type Metrics struct { } type Client struct { - UseIpfs bool - IpfsOnlineMode bool - IpfsMAddr string - IpfsUseForRetrieval bool + UseIpfs bool + IpfsOnlineMode bool + IpfsMAddr string + IpfsUseForRetrieval bool + // The maximum number of simultaneous data transfers between the client + // and storage providers SimultaneousTransfers uint64 }