feat(paych): add EnablePaymentChannelManager config option

[sumitvekariya]

add EnablePaymentChannelManager config option to disable payment channel manager 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.

Related Issues

#12718

Proposed Changes

• Config Addition: New EnablePaymentChannelManager boolean field in FullNode config struct
• Default Behavior: Payment channel manager disabled by default (false)
• Conditional Service Wiring: Modified dependency injection in node/builder_chain.go to only wire payment channel services when enabled
• Documentation: Updated config auto-generated documentation
• Changelog: Added entry to UNRELEASED section following contribution conventions

Additional Info

• Backward Compatibility: Full backward compatibility maintained - users can enable payment channels by setting EnablePaymentChannelManager: true
• Resource Savings: Eliminates unnecessary resource usage for nodes that don't use payment channels
• Testing: All existing payment channel tests pass, config tests updated with new default

Checklist

Before you mark the PR ready for review, please make sure that:

• Commits have a clear commit message.
• PR title conforms with contribution conventions
• Update CHANGELOG.md or signal that this change does not need it per contribution conventions
• New features have usage guidelines and / or documentation updates in
  • Lotus Documentation
  • Discussion Tutorials
• Tests exist for new functionality or change in behavior
• CI is green

[rvagg]

I think this is fine. Need some removals in CHANGELOG.md, make gen is needed to get CI to run and I'd like to do some tests with this locally.

For the record, the thing that bothers me about the payment channel manager is that it actively listens to head changes and looks for messages that match its schema of things to act on. Mostly this is a very minor activity, hardly measurable. But it does become measurable when you're running in lite mode, pointing to a remote, where head change listening requires API calls. I ran into this problem when doing gateway rate limiting because the gateway is effectively a lite client. So I expect that test will fail here and need to be adjusted.

It's not a huge concern, this is just a minor cleanup and we're not removing payment channel functionality or touching anything on chain. We're just preventing a node participating in payment channels while this option is turned off but it can easily be turned on again if ever required.

[rvagg]

Odd DI errors assembling lotus:

        	            	    missing type:
        	            	    	- *paychmgr.Manager (did you mean to Provide it?)

In theory, paychmgr.Manager shouldn't be needed with that chunk of code moved into a conditional in builder_chain.go, only this: Override(new(*paychmgr.Manager), modules.NewManager) and this: Override(HandlePaymentChannelManagerKey, modules.HandlePaychManager) should be caring about it as far as I can tell. So there must be some downstream dependency that depends on it indirectly. I'm just not seeing it. This will need some investigation and experimentation. @sumitvekariya you're welcome to tinker further with this to try and get to the bottom of it. The uber/fx framework (for DI / Direct Injection) we use in builder_chain.go is basically defining how to make the components and then it's up to the DI framework then uses that knowledge to piece together what it needs for a final Lotus instance. The error is suggesting that something still needs a *paychmgr.Manager but we've branched out the part where we tell it how to make one. So we need to figure out who needs it still.

[sumitvekariya]

Odd DI errors assembling lotus:

        	            	    missing type:
        	            	    	- *paychmgr.Manager (did you mean to Provide it?)

In theory, paychmgr.Manager shouldn't be needed with that chunk of code moved into a conditional in builder_chain.go, only this: Override(new(*paychmgr.Manager), modules.NewManager) and this: Override(HandlePaymentChannelManagerKey, modules.HandlePaychManager) should be caring about it as far as I can tell. So there must be some downstream dependency that depends on it indirectly. I'm just not seeing it. This will need some investigation and experimentation. @sumitvekariya you're welcome to tinker further with this to try and get to the bottom of it. The uber/fx framework (for DI / Direct Injection) we use in builder_chain.go is basically defining how to make the components and then it's up to the DI framework then uses that knowledge to piece together what it needs for a final Lotus instance. The error is suggesting that something still needs a *paychmgr.Manager but we've branched out the part where we tell it how to make one. So we need to figure out who needs it still.

Thanks for the guidance @rvagg! I found and fixed the issue. The problem was indeed a downstream dependency - the DI framework was having trouble with the field ordering in the config struct.

Solution

The fix was reordering the EnablePaymentChannelManager field in the FullNode config struct. Moving it from the end to an earlier position (after Chainstore, before Fevm) resolved the DI issue.

Status

✅ Build now succeeds - no more missing *paychmgr.Manager error
✅ make gen passes
✅ Payment channels properly disabled when EnablePaymentChannelManager = false

The solution was simpler than expected - no changes to PaychAPI were needed, just correcting the field positioning in the config struct.

[rvagg]

No, sadly, ordering in config isn't going to make a difference since it's loaded entirely first and then used later.

        	Error Trace:	/home/runner/work/lotus/lotus/itests/kit/ensemble.go:498
        	            				/home/runner/work/lotus/lotus/itests/daily_fees_test.go:123
        	Error:      	Received unexpected error:
        	            	starting node:
        	            	    github.com/filecoin-project/lotus/node.New
        	            	        /home/runner/work/lotus/lotus/node/builder.go:371
        	            	  - missing dependencies for function "reflect".makeFuncStub
        	            	    	/opt/hostedtoolcache/go/1.23.7/x64/src/reflect/asm_amd64.s:28:
        	            	    missing type:
        	            	    	- *paychmgr.Manager (did you mean to Provide it?)

[rvagg]

OK, I figured it out. The real problem is that our FullNodeAPI which implements all our external JSONRPC interface (the interface in api_full.go) requires a PaychAPI (confusingly there are multiple things with this name!) which implements those methods. Now by taking away a thing that implements those methods, FullNodeAPI can't assemble in a way that satisfies its interface because we don't make a paych.PaychAPI available for the DI system to assemble.

So this is what I've done:

• Turned this PaychAPI into an interface
• Switched the old PaychAPI to PaychImpl
• Introduced a new DisabledPaychAPI that returns errors for all of them
• Loaded in DisabledPaychAPI when EnablePaymentChannelManager is turned off
• Moved the EnablePaymentChannelManager into a new sub-section of the configuration named PaymentChannels so it's a bit neater than just a new top-level option

I also rebased on top of the current master and squashed all of the existing commits into one.

[Copilot]

Pull Request Overview

Adds a new EnablePaymentChannelManager flag to the full node config to disable the payment channel manager by default and wires in a stubbed API when disabled.

• Introduce PaymentChannelsConfig.EnablePaymentChannelManager (default: false)
• Conditional DI in builder_chain.go to use either PaychImpl or DisabledPaych
• Update docs, defaults, tests, and changelog

Reviewed Changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
node/impl/paych/paych.go	Define PaychAPI interface, real and disabled implementations
node/config/types.go	Add PaymentChannelsConfig struct with new boolean field
node/config/doc_gen.go	Update doc-gen mappings for new section
node/config/def.go	Set default EnablePaymentChannelManager: false
node/builder_chain.go	Conditionally wire payment channel manager or stub
itests/paych_cli_test.go	Enable flag in CLI tests
itests/paych_api_test.go	Enable flag in API tests and add disabled-mode tests
documentation/en/default-lotus-config.toml	Add default TOML snippet for [PaymentChannels]
CHANGELOG.md	Add entry for new config option

Comments suppressed due to low confidence (2)

node/config/doc_gen.go:357

• The "Type" entry for the PaymentChannels section uses "PaychConfig" but the actual struct is named "PaymentChannelsConfig". Update this for consistency in generated docs.

			Type: "PaychConfig",

node/impl/paych/paych.go:18

• [nitpick] There is already a PaychAPI in the paychmgr package, which can be confusing. Consider renaming this interface (e.g. PaymentChannelAPI or PaychHandler) for clarity.

// PaychAPI is the external interface that Lotus provides for interacting with payment channels.

[rvagg]

I've renamed the duplicate PaychAPI types in here so there's less confusion, if I don't do it now it may never get done! Most of this code is 5 years old and hasn't been touched since then.

[rvagg]

I'm going to have to ask for another review of this from someone else since most of the changeset is now mine. But I think it's good to go, and it's in 3 clear commits that I think can be rebase-merged as is.

[ZenGround0]

I love this. Very clean and a great simplification of the lotus process. Thanks all for getting this done.