feat(paych): add EnablePaymentChannelManager config option (#13139)

* feat(paych): add EnablePaymentChannelManager option & disable paych by default

This change introduces a new configuration option EnablePaymentChannelManager to control whether the payment channel manager is started on node startup.

- Added EnablePaymentChannelManager boolean field to FullNode config struct

- Set default value to false (disabled by default) since payment channels get minimal use on mainnet

- Added conditional wiring in node/builder_chain.go to only start payment channel manager when config option is enabled

- Updated config documentation with clear description of the option

This saves resources for light nodes and most full nodes that don't use payment channel functionality, while still allowing users to enable it when needed by setting EnablePaymentChannelManager: true in their config.

docs: add documentation for EnablePaymentChannelManager config option

- Updated default-lotus-config.toml with proper documentation for the new EnablePaymentChannelManager option

docs: update CHANGELOG.md with PR number #13139

Updated the CHANGELOG.md entry for EnablePaymentChannelManager feature with the actual PR number from the created pull request.

fix: address reviewer feedback on CHANGELOG.md - Fix PR number reference from PR_NUMBER to 13139 -  Remove unintended formatting changes as requested by reviewer

feat(paych): fix gen-check

docs: update config documentation after reordering EnablePaymentChannelManager field

* feat(paych): make disabled paych work & tests pass

fix(paych): add DisabledPaychAPI stub to return errors when external paych API is called

fix(cfg): introduce PaymentChannels top-level config option

fix(test): make integration tests work with paych disabled

* feat(paych): rename duplicate PaychAPI to avoid confusion

---------

Co-authored-by: Rod Vagg <[email protected]>

Author: sumitvekariya

CHANGELOG.md

@@ -30,6 +30,7 @@
   - default to PreCommit batching
   - default to ProveCommit aggregation
   - remove config options: AggregateCommits, AggregateAboveBaseFee, BatchPreCommitAboveBaseFee
+- feat(paych): add EnablePaymentChannelManager config option and disable payment channel manager by default ([filecoin-project/lotus#13139](https://github.com/filecoin-project/lotus/pull/13139))
 
 # Node v1.33.0 / 2025-05-08
 The Lotus v1.33.0 release introduces experimental v2 APIs with F3 awareness, featuring a new TipSet selection mechanism that significantly enhances how applications interact with the Filecoin blockchain. This release candidate also adds F3-aware Ethereum APIs via the /v2 endpoint.  All of the /v2 APIs implement intelligent fallback mechanisms between F3 and Expected Consensus and are exposed through the Lotus Gateway.

documentation/en/default-lotus-config.toml

@@ -395,3 +395,14 @@
   # env var: LOTUS_FAULTREPORTER_CONSENSUSFAULTREPORTERADDRESS
   #ConsensusFaultReporterAddress = ""
 
+
+[PaymentChannels]
+  # EnablePaymentChannelManager controls whether the payment channel manager is started.
+  # Default: false (disabled) - payment channels currently have minimal use on mainnet, although
+  # they remain a Filecoin protocol feature.
+  # Set to true to enable payment channel functionality if needed.
+  #
+  # type: bool
+  # env var: LOTUS_PAYMENTCHANNELS_ENABLEPAYMENTCHANNELMANAGER
+  #EnablePaymentChannelManager = false
+

itests/paych_api_test.go

@@ -9,6 +9,7 @@ import (
 	cbor "github.com/ipfs/go-ipld-cbor"
 	"github.com/stretchr/testify/require"
 
+	"github.com/filecoin-project/go-address"
 	"github.com/filecoin-project/go-state-types/abi"
 	"github.com/filecoin-project/go-state-types/big"
 	paychtypes "github.com/filecoin-project/go-state-types/builtin/v8/paych"
@@ -23,6 +24,7 @@ import (
 	"github.com/filecoin-project/lotus/chain/events/state"
 	"github.com/filecoin-project/lotus/chain/types"
 	"github.com/filecoin-project/lotus/itests/kit"
+	"github.com/filecoin-project/lotus/node/config"
 )
 
 func TestPaymentChannelsAPI(t *testing.T) {
@@ -38,9 +40,15 @@ func TestPaymentChannelsAPI(t *testing.T) {
 		miner           kit.TestMiner
 	)
 
+	enablePaychOpt := kit.WithCfgOpt(func(cfg *config.FullNode) error {
+		cfg.PaymentChannels = config.PaymentChannelsConfig{
+			EnablePaymentChannelManager: true,
+		}
+		return nil
+	})
 	ens := kit.NewEnsemble(t, kit.MockProofs()).
-		FullNode(&paymentCreator).
-		FullNode(&paymentReceiver).
+		FullNode(&paymentCreator, enablePaychOpt).
+		FullNode(&paymentReceiver, enablePaychOpt).
 		Miner(&miner, &paymentCreator, kit.WithAllSubsystems()).
 		Start().
 		InterconnectAll()
@@ -233,3 +241,45 @@ func waitForMessage(ctx context.Context, t *testing.T, paymentCreator kit.TestFu
 	t.Log("Confirmed", desc)
 	return res
 }
+
+func TestPaymentChannelsAPIDisabled(t *testing.T) {
+	ctx := context.Background()
+	kit.QuietMiningLogs()
+	full, _, _ := kit.EnsembleMinimal(t, kit.MockProofs())
+
+	// Call APIs to confirm they are not available
+	_, err := full.PaychGet(ctx, address.TestAddress, address.TestAddress2, abi.NewTokenAmount(0), api.PaychGetOpts{})
+	require.ErrorContains(t, err, "payment channel manager is disabled")
+	_, err = full.PaychFund(ctx, address.TestAddress, address.TestAddress2, abi.NewTokenAmount(0))
+	require.ErrorContains(t, err, "payment channel manager is disabled")
+	_, err = full.PaychAvailableFunds(ctx, address.TestAddress)
+	require.ErrorContains(t, err, "payment channel manager is disabled")
+	_, err = full.PaychAvailableFundsByFromTo(ctx, address.TestAddress, address.TestAddress2)
+	require.ErrorContains(t, err, "payment channel manager is disabled")
+	_, err = full.PaychGetWaitReady(ctx, cid.Undef)
+	require.ErrorContains(t, err, "payment channel manager is disabled")
+	_, err = full.PaychAllocateLane(ctx, address.TestAddress)
+	require.ErrorContains(t, err, "payment channel manager is disabled")
+	_, err = full.PaychNewPayment(ctx, address.TestAddress, address.TestAddress2, nil)
+	require.ErrorContains(t, err, "payment channel manager is disabled")
+	_, err = full.PaychList(ctx)
+	require.ErrorContains(t, err, "payment channel manager is disabled")
+	_, err = full.PaychStatus(ctx, address.TestAddress)
+	require.ErrorContains(t, err, "payment channel manager is disabled")
+	_, err = full.PaychSettle(ctx, address.TestAddress)
+	require.ErrorContains(t, err, "payment channel manager is disabled")
+	_, err = full.PaychCollect(ctx, address.TestAddress)
+	require.ErrorContains(t, err, "payment channel manager is disabled")
+	err = full.PaychVoucherCheckValid(ctx, address.TestAddress, &paychtypes.SignedVoucher{})
+	require.ErrorContains(t, err, "payment channel manager is disabled")
+	_, err = full.PaychVoucherCheckSpendable(ctx, address.TestAddress, &paychtypes.SignedVoucher{}, nil, nil)
+	require.ErrorContains(t, err, "payment channel manager is disabled")
+	_, err = full.PaychVoucherAdd(ctx, address.TestAddress, &paychtypes.SignedVoucher{}, nil, abi.NewTokenAmount(0))
+	require.ErrorContains(t, err, "payment channel manager is disabled")
+	_, err = full.PaychVoucherCreate(ctx, address.TestAddress, abi.NewTokenAmount(0), 0)
+	require.ErrorContains(t, err, "payment channel manager is disabled")
+	_, err = full.PaychVoucherList(ctx, address.TestAddress)
+	require.ErrorContains(t, err, "payment channel manager is disabled")
+	_, err = full.PaychVoucherSubmit(ctx, address.TestAddress, &paychtypes.SignedVoucher{}, nil, nil)
+	require.ErrorContains(t, err, "payment channel manager is disabled")
+}

itests/paych_cli_test.go

@@ -26,6 +26,7 @@ import (
 	"github.com/filecoin-project/lotus/chain/types"
 	"github.com/filecoin-project/lotus/cli/clicommands"
 	"github.com/filecoin-project/lotus/itests/kit"
+	"github.com/filecoin-project/lotus/node/config"
 )
 
 // TestPaymentChannelsBasic does a basic test to exercise the payment channel CLI
@@ -430,10 +431,15 @@ func getPaychState(ctx context.Context, t *testing.T, node kit.TestFullNode, chA
 
 func startPaychCreatorReceiverMiner(ctx context.Context, t *testing.T, paymentCreator *kit.TestFullNode, paymentReceiver *kit.TestFullNode, blocktime time.Duration) (address.Address, address.Address) {
 	var miner kit.TestMiner
-	opts := kit.ThroughRPC()
+	enablePaychOpt := kit.WithCfgOpt(func(cfg *config.FullNode) error {
+		cfg.PaymentChannels = config.PaymentChannelsConfig{
+			EnablePaymentChannelManager: true,
+		}
+		return nil
+	})
 	kit.NewEnsemble(t, kit.MockProofs()).
-		FullNode(paymentCreator, opts).
-		FullNode(paymentReceiver, opts).
+		FullNode(paymentCreator, kit.ThroughRPC(), enablePaychOpt).
+		FullNode(paymentReceiver, kit.ThroughRPC(), enablePaychOpt).
 		Miner(&miner, paymentCreator, kit.WithAllSubsystems()).
 		Start().
 		InterconnectAll().

node/builder_chain.go

@@ -43,6 +43,7 @@ import (
 	"github.com/filecoin-project/lotus/node/impl/full"
 	"github.com/filecoin-project/lotus/node/impl/gasutils"
 	"github.com/filecoin-project/lotus/node/impl/net"
+	"github.com/filecoin-project/lotus/node/impl/paych"
 	"github.com/filecoin-project/lotus/node/modules"
 	"github.com/filecoin-project/lotus/node/modules/dtypes"
 	"github.com/filecoin-project/lotus/node/modules/lp2p"
@@ -118,13 +119,6 @@ var ChainNode = Options(
 	Override(new(wallet.Default), From(new(*wallet.LocalWallet))),
 	Override(new(api.Wallet), From(new(wallet.MultiWallet))),
 
-	// Service: Payment channels
-	Override(new(paychmgr.PaychAPI), From(new(modules.PaychAPI))),
-	Override(new(*paychmgr.Store), modules.NewPaychStore),
-	Override(new(*paychmgr.Manager), modules.NewManager),
-	Override(HandlePaymentChannelManagerKey, modules.HandlePaychManager),
-	Override(SettlePaymentChannelsKey, settler.SettlePaymentChannels),
-
 	// Markets (storage)
 	Override(new(*market.FundManager), market.NewFundManager),
 
@@ -361,6 +355,18 @@ func ConfigFullNode(c interface{}) Option {
 				Override(InitChainIndexerKey, modules.InitChainIndexer(cfg.ChainIndexer)),
 			),
 		),
+
+		If(cfg.PaymentChannels.EnablePaymentChannelManager,
+			Override(new(paychmgr.ManagerNodeAPI), From(new(modules.PaychManagerNodeAPI))),
+			Override(new(*paychmgr.Store), modules.NewPaychStore),
+			Override(new(*paychmgr.Manager), modules.NewManager),
+			Override(HandlePaymentChannelManagerKey, modules.HandlePaychManager),
+			Override(SettlePaymentChannelsKey, settler.SettlePaymentChannels),
+			Override(new(paych.PaychAPI), From(new(paych.PaychImpl))),
+		),
+		If(!cfg.PaymentChannels.EnablePaymentChannelManager,
+			Override(new(paych.PaychAPI), new(paych.DisabledPaych)),
+		),
 	)
 }
 

node/config/def.go

@@ -100,6 +100,9 @@ func DefaultFullNode() *FullNode {
 			ReconcileEmptyIndex: false,
 			MaxReconcileTipsets: 3 * builtin.EpochsInDay,
 		},
+		PaymentChannels: PaymentChannelsConfig{
+			EnablePaymentChannelManager: false,
+		},
 	}
 }
 

node/config/doc_gen.go

@@ -18,15 +18,16 @@ type Common struct {
 // FullNode is a full node config
 type FullNode struct {
 	Common
-	Libp2p        Libp2p
-	Pubsub        Pubsub
-	Wallet        Wallet
-	Fees          FeeConfig
-	Chainstore    Chainstore
-	Fevm          FevmConfig
-	Events        EventsConfig
-	ChainIndexer  ChainIndexerConfig
-	FaultReporter FaultReporterConfig
+	Libp2p          Libp2p
+	Pubsub          Pubsub
+	Wallet          Wallet
+	Fees            FeeConfig
+	Chainstore      Chainstore
+	Fevm            FevmConfig
+	Events          EventsConfig
+	ChainIndexer    ChainIndexerConfig
+	FaultReporter   FaultReporterConfig
+	PaymentChannels PaymentChannelsConfig
 }
 
 // // Common
@@ -671,3 +672,11 @@ type FaultReporterConfig struct {
 	// rewards. This address should have adequate funds to cover gas fees.
 	ConsensusFaultReporterAddress string
 }
+
+type PaymentChannelsConfig struct {
+	// EnablePaymentChannelManager controls whether the payment channel manager is started.
+	// Default: false (disabled) - payment channels currently have minimal use on mainnet, although
+	// they remain a Filecoin protocol feature.
+	// Set to true to enable payment channel functionality if needed.
+	EnablePaymentChannelManager bool
+}