feat: add node configuration JSON schema

Author: BitcoinZavior

schemas/node_config.json

@@ -0,0 +1,287 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "LDK Node Configuration",
+  "description": "Configuration options for LDK Node Flutter. Used to configure a Node instance via Builder.",
+  "type": "object",
+  "properties": {
+    "network": {
+      "type": "string",
+      "enum": ["bitcoin", "testnet", "signet", "regtest"],
+      "description": "Bitcoin network to connect to. Use 'testnet' or 'signet' for development, 'bitcoin' for mainnet (real money)."
+    },
+    "storageDirPath": {
+      "type": "string",
+      "description": "Path to store node data (channels, wallet, keys). Must be writable. Use path_provider to get a valid directory."
+    },
+    "listeningAddresses": {
+      "type": "array",
+      "description": "IP addresses and TCP ports the node will listen on for incoming connections.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["hostname", "tcpIpV4", "tcpIpV6", "onionV3"],
+            "description": "Address type"
+          },
+          "addr": {
+            "type": "string",
+            "description": "IP address or hostname"
+          },
+          "port": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 65535,
+            "default": 9735,
+            "description": "TCP port number"
+          }
+        },
+        "required": ["addr", "port"]
+      },
+      "default": [{"type": "hostname", "addr": "0.0.0.0", "port": 9735}]
+    },
+    "announcementAddresses": {
+      "type": "array",
+      "description": "Addresses announced to the gossip network. Required for public channels.",
+      "items": {
+        "$ref": "#/properties/listeningAddresses/items"
+      }
+    },
+    "nodeAlias": {
+      "type": "string",
+      "maxLength": 32,
+      "description": "Node alias for gossip network announcements. Max 32 bytes UTF-8. Required for public channels."
+    },
+    "trustedPeers0Conf": {
+      "type": "array",
+      "description": "List of peer public keys (hex) allowed to open zero-confirmation channels. Use with caution.",
+      "items": {
+        "type": "string",
+        "pattern": "^[0-9a-fA-F]{66}$",
+        "description": "Peer's public key in hex format (33 bytes = 66 hex chars)"
+      },
+      "default": []
+    },
+    "probingLiquidityLimitMultiplier": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 3,
+      "description": "Multiplier for liquidity probing limits."
+    },
+    "anchorChannelsConfig": {
+      "type": "object",
+      "description": "Configuration for Anchor channels (improved fee handling).",
+      "properties": {
+        "trustedPeersNoReserve": {
+          "type": "array",
+          "description": "Peers trusted to handle anchor outputs. No reserve maintained for these peers.",
+          "items": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{66}$"
+          },
+          "default": []
+        },
+        "perChannelReserveSats": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 25000,
+          "description": "Satoshis reserved per anchor channel for emergency fee bumping."
+        }
+      }
+    },
+    "routeParameters": {
+      "type": "object",
+      "description": "Default routing parameters for payments. Can be overridden per-payment.",
+      "properties": {
+        "maxTotalRoutingFeeMsat": {
+          "oneOf": [
+            {
+              "type": "object",
+              "properties": {
+                "type": {"const": "noFeeCap"}
+              }
+            },
+            {
+              "type": "object",
+              "properties": {
+                "type": {"const": "feeCap"},
+                "amountMsat": {"type": "integer", "minimum": 0}
+              },
+              "required": ["amountMsat"]
+            }
+          ],
+          "description": "Maximum routing fees. Either 'noFeeCap' or 'feeCap' with amountMsat."
+        },
+        "maxTotalCltvExpiryDelta": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Maximum CLTV expiry delta for the entire route."
+        },
+        "maxPathCount": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum number of paths for multi-path payments (MPP)."
+        },
+        "maxChannelSaturationPowerOfHalf": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 8,
+          "default": 2,
+          "description": "Max channel utilization as power of 1/2. 0=100%, 1=50%, 2=25%, etc."
+        }
+      }
+    },
+    "chainDataSource": {
+      "type": "object",
+      "description": "Blockchain data source configuration.",
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "type": {"const": "esplora"},
+            "serverUrl": {"type": "string", "format": "uri"},
+            "backgroundSyncConfig": {"$ref": "#/definitions/backgroundSyncConfig"}
+          },
+          "required": ["type", "serverUrl"]
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": {"const": "electrum"},
+            "serverUrl": {"type": "string"},
+            "backgroundSyncConfig": {"$ref": "#/definitions/backgroundSyncConfig"}
+          },
+          "required": ["type", "serverUrl"]
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": {"const": "bitcoindRpc"},
+            "rpcHost": {"type": "string"},
+            "rpcPort": {"type": "integer", "minimum": 1, "maximum": 65535},
+            "rpcUser": {"type": "string"},
+            "rpcPassword": {"type": "string"}
+          },
+          "required": ["type", "rpcHost", "rpcPort", "rpcUser", "rpcPassword"]
+        }
+      ]
+    },
+    "gossipSource": {
+      "type": "object",
+      "description": "Source for Lightning network gossip data.",
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "type": {"const": "p2pNetwork"}
+          },
+          "required": ["type"]
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": {"const": "rapidGossipSync"},
+            "serverUrl": {"type": "string", "format": "uri"}
+          },
+          "required": ["type", "serverUrl"]
+        }
+      ]
+    },
+    "liquiditySource": {
+      "type": "object",
+      "description": "LSPS2 liquidity source for JIT channels.",
+      "properties": {
+        "address": {
+          "type": "object",
+          "properties": {
+            "addr": {"type": "string"},
+            "port": {"type": "integer", "minimum": 1, "maximum": 65535}
+          },
+          "required": ["addr", "port"]
+        },
+        "publicKey": {
+          "type": "string",
+          "pattern": "^[0-9a-fA-F]{66}$",
+          "description": "LSP node public key in hex"
+        },
+        "token": {
+          "type": "string",
+          "description": "Optional authentication token for LSP"
+        }
+      },
+      "required": ["address", "publicKey"]
+    },
+    "logLevel": {
+      "type": "string",
+      "enum": ["gossip", "trace", "debug", "info", "warn", "error"],
+      "default": "debug",
+      "description": "Minimum log level. 'gossip' is most verbose, 'error' is least."
+    }
+  },
+  "required": ["network", "storageDirPath"],
+  "definitions": {
+    "backgroundSyncConfig": {
+      "type": "object",
+      "description": "Background sync intervals. Set to null to disable background sync (manual only).",
+      "properties": {
+        "onchainWalletSyncIntervalSecs": {
+          "type": "integer",
+          "minimum": 10,
+          "default": 80,
+          "description": "On-chain wallet sync interval in seconds. Minimum 10."
+        },
+        "lightningWalletSyncIntervalSecs": {
+          "type": "integer",
+          "minimum": 10,
+          "default": 30,
+          "description": "Lightning wallet sync interval in seconds. Minimum 10."
+        },
+        "feeRateCacheUpdateIntervalSecs": {
+          "type": "integer",
+          "minimum": 10,
+          "default": 600,
+          "description": "Fee rate cache update interval in seconds. Minimum 10."
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "network": "testnet",
+      "storageDirPath": "/data/user/0/com.example.app/files/ldk_node",
+      "listeningAddresses": [
+        {"type": "hostname", "addr": "0.0.0.0", "port": 9735}
+      ],
+      "chainDataSource": {
+        "type": "esplora",
+        "serverUrl": "https://testnet.ltbl.io/api"
+      },
+      "gossipSource": {
+        "type": "rapidGossipSync",
+        "serverUrl": "https://testnet.ltbl.io/snapshot"
+      }
+    },
+    {
+      "network": "signet",
+      "storageDirPath": "/data/user/0/com.example.app/files/ldk_node",
+      "chainDataSource": {
+        "type": "esplora",
+        "serverUrl": "https://mutinynet.ltbl.io/api",
+        "backgroundSyncConfig": {
+          "onchainWalletSyncIntervalSecs": 60,
+          "lightningWalletSyncIntervalSecs": 60,
+          "feeRateCacheUpdateIntervalSecs": 600
+        }
+      },
+      "gossipSource": {
+        "type": "rapidGossipSync",
+        "serverUrl": "https://mutinynet.ltbl.io/snapshot"
+      },
+      "liquiditySource": {
+        "address": {"addr": "44.219.111.31", "port": 39735},
+        "publicKey": "0371d6fd7d75de2d0372d03ea00e8bacdacb50c27d0eaea0a76a0622eff1f5ef2b",
+        "token": "JZWN9YLW"
+      }
+    }
+  ]
+}