cmd/loop: add CLI support for scriptable autoloop

Add new flags to 'loop setparams' for configuring scriptable autoloop:

- --scriptautoloop: Enable/disable scriptable autoloop mode
- --scriptfile: Path to a Starlark script file (recommended for
  production - enables version control, syntax highlighting, and
  proper editing workflows)
- --script: Inline Starlark script for simple cases
- --scripttickinterval: Custom tick interval in seconds

Example usage:

    # Enable with script file (recommended)
    loop setparams --scriptautoloop --scriptfile /path/to/autoloop.star

    # Enable with inline script
    loop setparams --scriptautoloop --script 'decisions = []'

    # Disable
    loop setparams --scriptautoloop=false

The --scriptfile and --script flags are mutually exclusive. Scriptable
autoloop cannot be used together with easy autoloop.

Author: sputn1ck

cmd/loop/liquidity.go

@@ -5,6 +5,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"os"
 	"strconv"
 	"strings"
 
@@ -390,6 +391,34 @@ var setParamsCommand = &cli.Command{
 				"save on chain fees. Not setting this flag " +
 				"therefore might result in a lower swap fees",
 		},
+		&cli.BoolFlag{
+			Name: "scriptautoloop",
+			Usage: "set to true to enable scriptable autoloop " +
+				"using Starlark scripts. This allows custom " +
+				"swap logic with variables, functions, loops, " +
+				"and sorting. Mutually exclusive with " +
+				"easyautoloop and threshold rules.",
+		},
+		&cli.StringFlag{
+			Name: "scriptfile",
+			Usage: "path to a Starlark script file for " +
+				"scriptable autoloop. The script must set " +
+				"a 'decisions' variable to a list of swaps. " +
+				"Recommended for production use as it allows " +
+				"version control and proper editing.",
+		},
+		&cli.StringFlag{
+			Name: "script",
+			Usage: "inline Starlark script for scriptable " +
+				"autoloop. For simple scripts only; use " +
+				"--scriptfile for complex scripts.",
+		},
+		&cli.Uint64Flag{
+			Name: "scripttickinterval",
+			Usage: "custom tick interval in seconds for " +
+				"scriptable autoloop. If not set, uses " +
+				"the default 20-minute interval.",
+		},
 	},
 	Action: setParams,
 }
@@ -637,6 +666,48 @@ func setParams(ctx context.Context, cmd *cli.Command) error {
 		params.FastSwapPublication = true
 	}
 
+	// Handle scriptable autoloop flags.
+	if cmd.IsSet("scriptautoloop") {
+		params.ScriptableAutoloop = cmd.Bool("scriptautoloop")
+		flagSet = true
+	}
+
+	// Handle script content from file or inline.
+	scriptFileSet := cmd.IsSet("scriptfile")
+	scriptInlineSet := cmd.IsSet("script")
+
+	if scriptFileSet && scriptInlineSet {
+		return fmt.Errorf("cannot set both --scriptfile and --script; " +
+			"use one or the other")
+	}
+
+	if scriptFileSet {
+		scriptPath := cmd.String("scriptfile")
+		scriptBytes, err := os.ReadFile(scriptPath)
+		if err != nil {
+			return fmt.Errorf("failed to read script file %s: %w",
+				scriptPath, err)
+		}
+		params.ScriptableScript = string(scriptBytes)
+		flagSet = true
+	}
+
+	if scriptInlineSet {
+		params.ScriptableScript = cmd.String("script")
+		flagSet = true
+	}
+
+	if cmd.IsSet("scripttickinterval") {
+		params.ScriptableTickIntervalSec = cmd.Uint64("scripttickinterval")
+		flagSet = true
+	}
+
+	// Validate that scriptable autoloop is not used with easyautoloop.
+	if params.ScriptableAutoloop && params.EasyAutoloop {
+		return fmt.Errorf("scriptable autoloop cannot be used with " +
+			"easy autoloop; disable one before enabling the other")
+	}
+
 	if !flagSet {
 		return fmt.Errorf("at least one flag required to set params")
 	}

liquidity/liquidity.go

@@ -295,19 +295,22 @@ func (m *Manager) Run(ctx context.Context) error {
 		case <-m.cfg.AutoloopTicker.Ticks():
 			// Check which autoloop mode to use.
 			// Priority: scriptable > easy > threshold rules.
-			if m.params.ScriptableAutoloop {
+			switch {
+			case m.params.ScriptableAutoloop:
 				err := m.scriptableAutoLoop(ctx)
 				if err != nil {
 					log.Errorf("scriptable autoloop "+
 						"failed: %v", err)
 				}
-			} else if m.params.EasyAutoloop {
+
+			case m.params.EasyAutoloop:
 				err := m.easyAutoLoop(ctx)
 				if err != nil {
 					log.Errorf("easy autoloop failed: %v",
 						err)
 				}
-			} else {
+
+			default:
 				err := m.autoloop(ctx)
 				switch err {
 				case ErrNoRules:

liquidity/parameters.go

@@ -129,11 +129,11 @@ type Parameters struct {
 	// If set to false, the deadline is set to 30 minutes.
 	FastSwapPublication bool
 
-	// ScriptableAutoloop enables CEL-based scriptable autoloop mode.
+	// ScriptableAutoloop enables Starlark-based scriptable autoloop mode.
 	// This mode is mutually exclusive with EasyAutoloop and threshold rules.
 	ScriptableAutoloop bool
 
-	// ScriptableScript is the CEL expression to evaluate on each tick.
+	// ScriptableScript is the Starlark script to evaluate on each tick.
 	// Required when ScriptableAutoloop is true.
 	ScriptableScript string
 
@@ -653,13 +653,13 @@ func ParametersToRpc(cfg Parameters) (*clientrpc.LiquidityParameters,
 		HtlcConfTarget:             cfg.HtlcConfTarget,
 		EasyAutoloop:               cfg.EasyAutoloop,
 		EasyAutoloopLocalTargetSat: uint64(cfg.EasyAutoloopTarget),
-		Account:                      cfg.Account,
-		AccountAddrType:              addrType,
-		EasyAssetParams:              easyAssetMap,
-		FastSwapPublication:          cfg.FastSwapPublication,
-		ScriptableAutoloop:           cfg.ScriptableAutoloop,
-		ScriptableScript:             cfg.ScriptableScript,
-		ScriptableTickIntervalSec:    uint64(cfg.ScriptableTickInterval / time.Second),
+		Account:                    cfg.Account,
+		AccountAddrType:            addrType,
+		EasyAssetParams:            easyAssetMap,
+		FastSwapPublication:        cfg.FastSwapPublication,
+		ScriptableAutoloop:         cfg.ScriptableAutoloop,
+		ScriptableScript:           cfg.ScriptableScript,
+		ScriptableTickIntervalSec:  uint64(cfg.ScriptableTickInterval / time.Second),
 	}
 	// Set excluded peers for easy autoloop.
 	rpcCfg.EasyAutoloopExcludedPeers = make(

liquidity/script/builtins.go

@@ -7,7 +7,7 @@ import (
 )
 
 // loopOutBuiltin creates a loop out swap decision.
-// Usage: loop_out(amount, channel_ids) or loop_out(amount, channel_ids, priority)
+// Usage: loop_out(amount, channel_ids) or loop_out(amount, channel_ids, priority).
 func loopOutBuiltin(thread *starlark.Thread, fn *starlark.Builtin,
 	args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
 
@@ -65,7 +65,7 @@ func loopOutBuiltin(thread *starlark.Thread, fn *starlark.Builtin,
 }
 
 // loopInBuiltin creates a loop in swap decision.
-// Usage: loop_in(amount, peer_pubkey) or loop_in(amount, peer_pubkey, priority)
+// Usage: loop_in(amount, peer_pubkey) or loop_in(amount, peer_pubkey, priority).
 func loopInBuiltin(thread *starlark.Thread, fn *starlark.Builtin,
 	args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
 

liquidity/script_equivalence_test.go

@@ -20,7 +20,7 @@ import (
 )
 
 // EasyAutoloopStarlarkScript is a Starlark script that replicates easy-autoloop.
-// Target: 100000 sats (embedded in script)
+// Target: 100000 sats (embedded in script).
 const EasyAutoloopStarlarkScript = `
 # Easy autoloop equivalent script in Starlark
 # Target: 100000 sats
@@ -58,7 +58,7 @@ def autoloop():
     swap_amount = min(best.local_balance, amount)
     return [loop_out(swap_amount, [best.channel_id])]
 
-# Execute and return decisions
+# Execute and store result.
 decisions = autoloop()
 `
 
@@ -335,13 +335,15 @@ func TestScriptableAutoloopIntegration(t *testing.T) {
 		},
 		Restrictions: func(ctx context.Context, swapType swap.Type,
 			initiator string) (*Restrictions, error) {
+
 			return &Restrictions{
 				Minimum: 10000,
 				Maximum: 1000000,
 			}, nil
 		},
 		LoopOutQuote: func(ctx context.Context,
 			req *loop.LoopOutQuoteRequest) (*loop.LoopOutQuote, error) {
+
 			return &loop.LoopOutQuote{
 				SwapFee:      100,
 				PrepayAmount: 1000,