Skip to content

jmcore.settings

jmcore.settings

Unified settings management for JoinMarket components.

This module provides a centralized configuration system using pydantic-settings that supports: 1. TOML configuration file (~/.joinmarket-ng/config.toml) 2. Environment variables 3. CLI arguments (via typer, handled by components)

Priority (highest to lowest): 1. CLI arguments 2. Environment variables 3. Config file 4. Default values

The config file is auto-generated on first run with all settings commented out, allowing users to selectively override only the settings they want to change. This approach facilitates software updates since unchanged defaults can be updated without user intervention.

Usage: from jmcore.settings import get_settings, JoinMarketSettings

# Get settings (loads from all sources with proper priority)
settings = get_settings()

# Access common settings
print(settings.tor.socks_host)
print(settings.bitcoin.rpc_url)

Environment Variable Naming: - Use uppercase with double underscore for nested settings - Examples: TOR__SOCKS_HOST, BITCOIN__RPC_URL, MAKER__MIN_SIZE - Maps to TOML sections: TOR__SOCKS_HOST -> [tor] socks_host

Attributes

DEFAULT_DIRECTORY_SERVERS: dict[str, list[str]] = {'mainnet': ['satoshi2vcg5e2ept7tjkzlkpomkobqmgtsjzegg6wipnoajadissead.onion:5222', 'coinjointovy3eq5fjygdwpkbcdx63d7vd4g32mw7y553uj3kjjzkiqd.onion:5222', 'nakamotourflxwjnjpnrk7yc2nhkf6r62ed4gdfxmmn5f4saw5q5qoyd.onion:5222', 'odpwaf67rs5226uabcamvypg3y4bngzmfk7255flcdodesqhsvkptaid.onion:5222', 'jmarketxf5wc4aldf3slm5u6726zsky52bqnfv6qyxe5hnafgly6yuyd.onion:5222'], 'signet': ['signetvaxgd3ivj4tml4g6ed3samaa2rscre2gyeyohncmwk4fbesiqd.onion:5222'], 'testnet': [], 'regtest': []} module-attribute

__all__ = ['JoinMarketSettings', 'TorSettings', 'BitcoinSettings', 'NetworkSettings', 'WalletSettings', 'NotificationSettings', 'MakerSettings', 'TakerSettings', 'DirectoryServerSettings', 'OrderbookWatcherSettings', 'LoggingSettings', 'get_settings', 'reset_settings', 'get_config_path', 'generate_config_template', 'ensure_config_file', 'DEFAULT_DIRECTORY_SERVERS'] module-attribute

Classes

BitcoinSettings

Bases: BaseModel

Bitcoin backend configuration.

Source code in jmcore/src/jmcore/settings.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
class BitcoinSettings(BaseModel):
    """Bitcoin backend configuration."""

    backend_type: str = Field(
        default="descriptor_wallet",
        description="Backend type: scantxoutset, descriptor_wallet, or neutrino",
    )
    rpc_url: str = Field(
        default="http://127.0.0.1:8332",
        description="Bitcoin Core RPC URL",
    )
    rpc_user: str = Field(
        default="",
        description="Bitcoin Core RPC username",
    )
    rpc_password: SecretStr = Field(
        default=SecretStr(""),
        description="Bitcoin Core RPC password",
    )
    descriptor_wallet_name: str = Field(
        default="jm_descriptor_wallet",
        description="Name of the descriptor wallet to use in Bitcoin Core",
    )
    neutrino_url: str = Field(
        default="http://127.0.0.1:8334",
        description="Neutrino REST API URL (for neutrino backend)",
    )
Attributes
backend_type: str = Field(default='descriptor_wallet', description='Backend type: scantxoutset, descriptor_wallet, or neutrino') class-attribute instance-attribute
descriptor_wallet_name: str = Field(default='jm_descriptor_wallet', description='Name of the descriptor wallet to use in Bitcoin Core') class-attribute instance-attribute
neutrino_url: str = Field(default='http://127.0.0.1:8334', description='Neutrino REST API URL (for neutrino backend)') class-attribute instance-attribute
rpc_password: SecretStr = Field(default=(SecretStr('')), description='Bitcoin Core RPC password') class-attribute instance-attribute
rpc_url: str = Field(default='http://127.0.0.1:8332', description='Bitcoin Core RPC URL') class-attribute instance-attribute
rpc_user: str = Field(default='', description='Bitcoin Core RPC username') class-attribute instance-attribute

DirectoryServerSettings

Bases: BaseModel

Directory server specific settings.

Source code in jmcore/src/jmcore/settings.py 
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
class DirectoryServerSettings(BaseModel):
    """Directory server specific settings."""

    host: str = Field(
        default="127.0.0.1",
        description="Host address to bind to",
    )
    port: int = Field(
        default=5222,
        ge=0,
        le=65535,
        description="Port to listen on (0 = let OS assign)",
    )
    max_peers: int = Field(
        default=10000,
        ge=1,
        description="Maximum number of connected peers",
    )
    max_message_size: int = Field(
        default=2097152,
        ge=1024,
        description="Maximum message size in bytes (2MB default)",
    )
    max_line_length: int = Field(
        default=65536,
        ge=1024,
        description="Maximum JSON-line message length (64KB default)",
    )
    max_json_nesting_depth: int = Field(
        default=10,
        ge=1,
        description="Maximum nesting depth for JSON parsing",
    )
    message_rate_limit: int = Field(
        default=500,
        ge=1,
        description="Messages per second (sustained)",
    )
    message_burst_limit: int = Field(
        default=1000,
        ge=1,
        description="Maximum burst size",
    )
    rate_limit_disconnect_threshold: int = Field(
        default=0,
        ge=0,
        description="Disconnect after N rate limit violations (0 = never disconnect)",
    )
    broadcast_batch_size: int = Field(
        default=50,
        ge=1,
        description="Batch size for concurrent broadcasts",
    )
    health_check_host: str = Field(
        default="127.0.0.1",
        description="Host for health check endpoint",
    )
    health_check_port: int = Field(
        default=8080,
        ge=0,
        le=65535,
        description="Port for health check endpoint (0 = let OS assign)",
    )
    motd: str = Field(
        default="JoinMarket NG Directory Server https://github.com/joinmarket-ng/joinmarket-ng/",
        description="Message of the day sent to clients",
    )
Attributes
broadcast_batch_size: int = Field(default=50, ge=1, description='Batch size for concurrent broadcasts') class-attribute instance-attribute
health_check_host: str = Field(default='127.0.0.1', description='Host for health check endpoint') class-attribute instance-attribute
health_check_port: int = Field(default=8080, ge=0, le=65535, description='Port for health check endpoint (0 = let OS assign)') class-attribute instance-attribute
host: str = Field(default='127.0.0.1', description='Host address to bind to') class-attribute instance-attribute
max_json_nesting_depth: int = Field(default=10, ge=1, description='Maximum nesting depth for JSON parsing') class-attribute instance-attribute
max_line_length: int = Field(default=65536, ge=1024, description='Maximum JSON-line message length (64KB default)') class-attribute instance-attribute
max_message_size: int = Field(default=2097152, ge=1024, description='Maximum message size in bytes (2MB default)') class-attribute instance-attribute
max_peers: int = Field(default=10000, ge=1, description='Maximum number of connected peers') class-attribute instance-attribute
message_burst_limit: int = Field(default=1000, ge=1, description='Maximum burst size') class-attribute instance-attribute
message_rate_limit: int = Field(default=500, ge=1, description='Messages per second (sustained)') class-attribute instance-attribute
motd: str = Field(default='JoinMarket NG Directory Server https://github.com/joinmarket-ng/joinmarket-ng/', description='Message of the day sent to clients') class-attribute instance-attribute
port: int = Field(default=5222, ge=0, le=65535, description='Port to listen on (0 = let OS assign)') class-attribute instance-attribute
rate_limit_disconnect_threshold: int = Field(default=0, ge=0, description='Disconnect after N rate limit violations (0 = never disconnect)') class-attribute instance-attribute

JoinMarketSettings

Bases: BaseSettings

Main JoinMarket settings class.

Loads configuration from multiple sources with the following priority: 1. CLI arguments (not handled here, passed to component init) 2. Environment variables 3. TOML config file (~/.joinmarket-ng/config.toml) 4. Default values

Source code in jmcore/src/jmcore/settings.py 
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
class JoinMarketSettings(BaseSettings):
    """
    Main JoinMarket settings class.

    Loads configuration from multiple sources with the following priority:
    1. CLI arguments (not handled here, passed to component __init__)
    2. Environment variables
    3. TOML config file (~/.joinmarket-ng/config.toml)
    4. Default values
    """

    model_config = SettingsConfigDict(
        env_prefix="",  # No prefix by default, use env_nested_delimiter for nested
        env_nested_delimiter="__",
        case_sensitive=False,
        extra="ignore",  # Ignore unknown fields (for forward compatibility)
    )

    # Marker for config file path discovery
    _config_file_path: ClassVar[Path | None] = None

    # Core settings
    data_dir: Path | None = Field(
        default=None,
        description="Data directory (defaults to ~/.joinmarket-ng)",
    )

    # Nested settings groups
    tor: TorSettings = Field(default_factory=TorSettings)
    bitcoin: BitcoinSettings = Field(default_factory=BitcoinSettings)
    network_config: NetworkSettings = Field(default_factory=NetworkSettings)
    wallet: WalletSettings = Field(default_factory=WalletSettings)
    notifications: NotificationSettings = Field(default_factory=NotificationSettings)
    logging: LoggingSettings = Field(default_factory=LoggingSettings)

    # Component-specific settings
    maker: MakerSettings = Field(default_factory=MakerSettings)
    taker: TakerSettings = Field(default_factory=TakerSettings)
    directory_server: DirectoryServerSettings = Field(default_factory=DirectoryServerSettings)
    orderbook_watcher: OrderbookWatcherSettings = Field(default_factory=OrderbookWatcherSettings)

    @classmethod
    def settings_customise_sources(
        cls,
        settings_cls: type[BaseSettings],
        init_settings: PydanticBaseSettingsSource,
        env_settings: PydanticBaseSettingsSource,
        dotenv_settings: PydanticBaseSettingsSource,
        file_secret_settings: PydanticBaseSettingsSource,
    ) -> tuple[PydanticBaseSettingsSource, ...]:
        """
        Customize settings sources and their priority.

        Priority (highest to lowest):
        1. init_settings (CLI arguments passed to constructor)
        2. env_settings (environment variables with __ delimiter)
        3. toml_settings (config.toml file)
        4. defaults (in field definitions)
        """
        toml_source = TomlConfigSettingsSource(settings_cls)
        comma_env = _CommaListEnvSettingsSource(settings_cls)
        return (
            init_settings,
            comma_env,
            toml_source,
        )

    def get_data_dir(self) -> Path:
        """Get the data directory, using default if not set."""
        if self.data_dir is not None:
            return self.data_dir
        return get_default_data_dir()

    def get_directory_servers(self) -> list[str]:
        """Get directory servers, using network defaults if not set."""
        if self.network_config.directory_servers:
            return self.network_config.directory_servers
        network_name = self.network_config.network.value
        return DEFAULT_DIRECTORY_SERVERS.get(network_name, [])
Attributes
bitcoin: BitcoinSettings = Field(default_factory=BitcoinSettings) class-attribute instance-attribute
data_dir: Path | None = Field(default=None, description='Data directory (defaults to ~/.joinmarket-ng)') class-attribute instance-attribute
directory_server: DirectoryServerSettings = Field(default_factory=DirectoryServerSettings) class-attribute instance-attribute
logging: LoggingSettings = Field(default_factory=LoggingSettings) class-attribute instance-attribute
maker: MakerSettings = Field(default_factory=MakerSettings) class-attribute instance-attribute
model_config = SettingsConfigDict(env_prefix='', env_nested_delimiter='__', case_sensitive=False, extra='ignore') class-attribute instance-attribute
network_config: NetworkSettings = Field(default_factory=NetworkSettings) class-attribute instance-attribute
notifications: NotificationSettings = Field(default_factory=NotificationSettings) class-attribute instance-attribute
orderbook_watcher: OrderbookWatcherSettings = Field(default_factory=OrderbookWatcherSettings) class-attribute instance-attribute
taker: TakerSettings = Field(default_factory=TakerSettings) class-attribute instance-attribute
tor: TorSettings = Field(default_factory=TorSettings) class-attribute instance-attribute
wallet: WalletSettings = Field(default_factory=WalletSettings) class-attribute instance-attribute
Functions
get_data_dir() -> Path

Get the data directory, using default if not set.

Source code in jmcore/src/jmcore/settings.py 
788
789
790
791
792
def get_data_dir(self) -> Path:
    """Get the data directory, using default if not set."""
    if self.data_dir is not None:
        return self.data_dir
    return get_default_data_dir()
get_directory_servers() -> list[str]

Get directory servers, using network defaults if not set.

Source code in jmcore/src/jmcore/settings.py 
794
795
796
797
798
799
def get_directory_servers(self) -> list[str]:
    """Get directory servers, using network defaults if not set."""
    if self.network_config.directory_servers:
        return self.network_config.directory_servers
    network_name = self.network_config.network.value
    return DEFAULT_DIRECTORY_SERVERS.get(network_name, [])
settings_customise_sources(settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...] classmethod

Customize settings sources and their priority.

Priority (highest to lowest): 1. init_settings (CLI arguments passed to constructor) 2. env_settings (environment variables with __ delimiter) 3. toml_settings (config.toml file) 4. defaults (in field definitions)

Source code in jmcore/src/jmcore/settings.py 
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
@classmethod
def settings_customise_sources(
    cls,
    settings_cls: type[BaseSettings],
    init_settings: PydanticBaseSettingsSource,
    env_settings: PydanticBaseSettingsSource,
    dotenv_settings: PydanticBaseSettingsSource,
    file_secret_settings: PydanticBaseSettingsSource,
) -> tuple[PydanticBaseSettingsSource, ...]:
    """
    Customize settings sources and their priority.

    Priority (highest to lowest):
    1. init_settings (CLI arguments passed to constructor)
    2. env_settings (environment variables with __ delimiter)
    3. toml_settings (config.toml file)
    4. defaults (in field definitions)
    """
    toml_source = TomlConfigSettingsSource(settings_cls)
    comma_env = _CommaListEnvSettingsSource(settings_cls)
    return (
        init_settings,
        comma_env,
        toml_source,
    )

LoggingSettings

Bases: BaseModel

Logging configuration.

Source code in jmcore/src/jmcore/settings.py 
667
668
669
670
671
672
673
674
675
676
677
class LoggingSettings(BaseModel):
    """Logging configuration."""

    level: str = Field(
        default="INFO",
        description="Log level: TRACE, DEBUG, INFO, WARNING, ERROR",
    )
    sensitive: bool = Field(
        default=False,
        description="Enable sensitive logging (mnemonics, keys)",
    )
Attributes
level: str = Field(default='INFO', description='Log level: TRACE, DEBUG, INFO, WARNING, ERROR') class-attribute instance-attribute
sensitive: bool = Field(default=False, description='Enable sensitive logging (mnemonics, keys)') class-attribute instance-attribute

MakerSettings

Bases: BaseModel

Maker-specific settings.

Source code in jmcore/src/jmcore/settings.py 
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
class MakerSettings(BaseModel):
    """Maker-specific settings."""

    min_size: int = Field(
        default=DUST_THRESHOLD,
        ge=0,
        description="Minimum CoinJoin amount in satoshis (default: dust threshold)",
    )
    offer_type: str = Field(
        default="sw0reloffer",
        description="Offer type: sw0reloffer (relative) or sw0absoffer (absolute)",
    )
    cj_fee_relative: str = Field(
        default="0.001",
        description="Relative CoinJoin fee (0.001 = 0.1%)",
    )
    cj_fee_absolute: int = Field(
        default=500,
        ge=0,
        description="Absolute CoinJoin fee in satoshis",
    )
    tx_fee_contribution: int = Field(
        default=0,
        ge=0,
        description="Transaction fee contribution in satoshis",
    )
    min_confirmations: int = Field(
        default=1,
        ge=0,
        description="Minimum confirmations for UTXOs",
    )
    merge_algorithm: str = Field(
        default="default",
        description="UTXO selection: default, gradual, greedy, random",
    )
    session_timeout_sec: int = Field(
        default=300,
        ge=60,
        description="Maximum time for a CoinJoin session",
    )
    pending_tx_timeout_min: int = Field(
        default=60,
        ge=10,
        le=1440,
        description="Minutes before marking unbroadcast CoinJoins as failed",
    )
    rescan_interval_sec: int = Field(
        default=600,
        ge=60,
        description="Interval for periodic wallet rescans",
    )
    # Hidden service settings
    onion_serving_host: str = Field(
        default="127.0.0.1",
        description="Bind address for incoming connections",
    )
    onion_serving_port: int = Field(
        default=5222,
        ge=0,
        le=65535,
        description="Port for incoming onion connections",
    )
    # Rate limiting
    message_rate_limit: int = Field(
        default=10,
        ge=1,
        description="Messages per second per peer (sustained)",
    )
    message_burst_limit: int = Field(
        default=100,
        ge=1,
        description="Maximum burst messages per peer",
    )

    @field_validator("cj_fee_relative", mode="before")
    @classmethod
    def normalize_cj_fee_relative(cls, v: str | float | int) -> str:
        """
        Normalize cj_fee_relative to avoid scientific notation.

        Pydantic may coerce float values (from env vars, TOML, or JSON) to strings,
        which can result in scientific notation for small values (e.g., 1e-05).
        The JoinMarket protocol expects decimal notation (e.g., 0.00001).
        """
        if isinstance(v, (int, float)):
            # Use Decimal to preserve precision and avoid scientific notation
            return format(Decimal(str(v)), "f")
        # Already a string - check if it contains scientific notation
        if "e" in v.lower():
            try:
                return format(Decimal(v), "f")
            except InvalidOperation:
                pass  # Let pydantic handle the validation error
        return v
Attributes
cj_fee_absolute: int = Field(default=500, ge=0, description='Absolute CoinJoin fee in satoshis') class-attribute instance-attribute
cj_fee_relative: str = Field(default='0.001', description='Relative CoinJoin fee (0.001 = 0.1%)') class-attribute instance-attribute
merge_algorithm: str = Field(default='default', description='UTXO selection: default, gradual, greedy, random') class-attribute instance-attribute
message_burst_limit: int = Field(default=100, ge=1, description='Maximum burst messages per peer') class-attribute instance-attribute
message_rate_limit: int = Field(default=10, ge=1, description='Messages per second per peer (sustained)') class-attribute instance-attribute
min_confirmations: int = Field(default=1, ge=0, description='Minimum confirmations for UTXOs') class-attribute instance-attribute
min_size: int = Field(default=DUST_THRESHOLD, ge=0, description='Minimum CoinJoin amount in satoshis (default: dust threshold)') class-attribute instance-attribute
offer_type: str = Field(default='sw0reloffer', description='Offer type: sw0reloffer (relative) or sw0absoffer (absolute)') class-attribute instance-attribute
onion_serving_host: str = Field(default='127.0.0.1', description='Bind address for incoming connections') class-attribute instance-attribute
onion_serving_port: int = Field(default=5222, ge=0, le=65535, description='Port for incoming onion connections') class-attribute instance-attribute
pending_tx_timeout_min: int = Field(default=60, ge=10, le=1440, description='Minutes before marking unbroadcast CoinJoins as failed') class-attribute instance-attribute
rescan_interval_sec: int = Field(default=600, ge=60, description='Interval for periodic wallet rescans') class-attribute instance-attribute
session_timeout_sec: int = Field(default=300, ge=60, description='Maximum time for a CoinJoin session') class-attribute instance-attribute
tx_fee_contribution: int = Field(default=0, ge=0, description='Transaction fee contribution in satoshis') class-attribute instance-attribute
Functions
normalize_cj_fee_relative(v: str | float | int) -> str classmethod

Normalize cj_fee_relative to avoid scientific notation.

Pydantic may coerce float values (from env vars, TOML, or JSON) to strings, which can result in scientific notation for small values (e.g., 1e-05). The JoinMarket protocol expects decimal notation (e.g., 0.00001).

Source code in jmcore/src/jmcore/settings.py 
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
@field_validator("cj_fee_relative", mode="before")
@classmethod
def normalize_cj_fee_relative(cls, v: str | float | int) -> str:
    """
    Normalize cj_fee_relative to avoid scientific notation.

    Pydantic may coerce float values (from env vars, TOML, or JSON) to strings,
    which can result in scientific notation for small values (e.g., 1e-05).
    The JoinMarket protocol expects decimal notation (e.g., 0.00001).
    """
    if isinstance(v, (int, float)):
        # Use Decimal to preserve precision and avoid scientific notation
        return format(Decimal(str(v)), "f")
    # Already a string - check if it contains scientific notation
    if "e" in v.lower():
        try:
            return format(Decimal(v), "f")
        except InvalidOperation:
            pass  # Let pydantic handle the validation error
    return v

NetworkSettings

Bases: BaseModel

Network configuration.

Source code in jmcore/src/jmcore/settings.py 
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
class NetworkSettings(BaseModel):
    """Network configuration."""

    network: NetworkType = Field(
        default=NetworkType.MAINNET,
        description="JoinMarket protocol network (mainnet, testnet, signet, regtest)",
    )
    bitcoin_network: NetworkType | None = Field(
        default=None,
        description="Bitcoin network for address generation (defaults to network)",
    )
    directory_servers: list[str] = Field(
        default_factory=list,
        description="Directory server addresses (host:port). Uses defaults if empty.",
    )

    @field_validator("directory_servers", mode="before")
    @classmethod
    def parse_directory_servers(cls, v: Any) -> Any:
        """Accept JSON arrays, comma-separated strings, or plain single values.

        pydantic-settings passes list[str] env vars through json.loads(), which
        requires JSON format. This validator also accepts plain comma-separated
        strings so that e.g. NETWORK_CONFIG__DIRECTORY_SERVERS=host:port works.
        """
        import json

        if isinstance(v, str):
            v = v.strip()
            # Try JSON first (handles '["a","b"]' or '"a"' forms)
            try:
                parsed = json.loads(v)
                if isinstance(parsed, list):
                    return [s.strip() for s in parsed if s.strip()]
                if isinstance(parsed, str):
                    return [parsed.strip()] if parsed.strip() else []
            except (json.JSONDecodeError, ValueError):
                pass
            # Fall back to comma-separated plain string
            return [s.strip() for s in v.split(",") if s.strip()]
        return v
Attributes
bitcoin_network: NetworkType | None = Field(default=None, description='Bitcoin network for address generation (defaults to network)') class-attribute instance-attribute
directory_servers: list[str] = Field(default_factory=list, description='Directory server addresses (host:port). Uses defaults if empty.') class-attribute instance-attribute
network: NetworkType = Field(default=(NetworkType.MAINNET), description='JoinMarket protocol network (mainnet, testnet, signet, regtest)') class-attribute instance-attribute
Functions
parse_directory_servers(v: Any) -> Any classmethod

Accept JSON arrays, comma-separated strings, or plain single values.

pydantic-settings passes list[str] env vars through json.loads(), which requires JSON format. This validator also accepts plain comma-separated strings so that e.g. NETWORK_CONFIG__DIRECTORY_SERVERS=host:port works.

Source code in jmcore/src/jmcore/settings.py 
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
@field_validator("directory_servers", mode="before")
@classmethod
def parse_directory_servers(cls, v: Any) -> Any:
    """Accept JSON arrays, comma-separated strings, or plain single values.

    pydantic-settings passes list[str] env vars through json.loads(), which
    requires JSON format. This validator also accepts plain comma-separated
    strings so that e.g. NETWORK_CONFIG__DIRECTORY_SERVERS=host:port works.
    """
    import json

    if isinstance(v, str):
        v = v.strip()
        # Try JSON first (handles '["a","b"]' or '"a"' forms)
        try:
            parsed = json.loads(v)
            if isinstance(parsed, list):
                return [s.strip() for s in parsed if s.strip()]
            if isinstance(parsed, str):
                return [parsed.strip()] if parsed.strip() else []
        except (json.JSONDecodeError, ValueError):
            pass
        # Fall back to comma-separated plain string
        return [s.strip() for s in v.split(",") if s.strip()]
    return v

NotificationSettings

Bases: BaseModel

Notification system configuration.

Source code in jmcore/src/jmcore/settings.py 
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
class NotificationSettings(BaseModel):
    """Notification system configuration."""

    enabled: bool = Field(
        default=False,
        description="Enable notifications (requires urls to be set)",
    )
    urls: list[str] = Field(
        default_factory=list,
        description='Apprise notification URLs (e.g., ["tgram://bottoken/ChatID", "gotify://hostname/token"])',
    )
    title_prefix: str = Field(
        default="JoinMarket NG",
        description="Prefix for notification titles",
    )
    component_name: str = Field(
        default="",
        description="Component name in notification titles (e.g., 'Maker', 'Taker'). "
        "Usually set programmatically by each component.",
    )
    include_amounts: bool = Field(
        default=True,
        description="Include amounts in notifications",
    )
    include_txids: bool = Field(
        default=False,
        description="Include transaction IDs in notifications (privacy risk)",
    )
    include_nick: bool = Field(
        default=True,
        description="Include peer nicks in notifications",
    )
    use_tor: bool = Field(
        default=True,
        description="Route notifications through Tor SOCKS proxy",
    )
    # Event type toggles
    notify_fill: bool = Field(default=True, description="Notify on !fill requests")
    notify_rejection: bool = Field(default=True, description="Notify on rejections")
    notify_signing: bool = Field(default=True, description="Notify on transaction signing")
    notify_mempool: bool = Field(default=True, description="Notify on mempool detection")
    notify_confirmed: bool = Field(default=True, description="Notify on confirmation")
    notify_nick_change: bool = Field(default=True, description="Notify on nick change")
    notify_disconnect: bool = Field(
        default=False,
        description="Notify on individual directory server disconnect/reconnect (noisy)",
    )
    notify_all_disconnect: bool = Field(
        default=True,
        description="Notify when ALL directory servers are disconnected (critical)",
    )
    notify_coinjoin_start: bool = Field(default=True, description="Notify on CoinJoin start")
    notify_coinjoin_complete: bool = Field(default=True, description="Notify on CoinJoin complete")
    notify_coinjoin_failed: bool = Field(default=True, description="Notify on CoinJoin failure")
    notify_peer_events: bool = Field(default=False, description="Notify on peer connect/disconnect")
    notify_rate_limit: bool = Field(default=True, description="Notify on rate limit bans")
    notify_startup: bool = Field(default=True, description="Notify on component startup")
    notify_summary: bool = Field(
        default=True,
        description="Send periodic summary notifications with CoinJoin stats",
    )
    summary_interval_hours: int = Field(
        default=24,
        ge=1,
        le=168,
        description=(
            "Interval in hours between summary notifications (1-168). "
            "Common values: 24 (daily), 168 (weekly)"
        ),
    )
    check_for_updates: bool = Field(
        default=False,
        description=(
            "Check GitHub for new releases and include version info in summary notifications. "
            "PRIVACY WARNING: This polls the GitHub API (api.github.com) each summary interval. "
            "The request is routed through Tor when use_tor is enabled, but GitHub will still "
            "see the Tor exit node IP. Opt-in only."
        ),
    )
    # Retry settings
    retry_enabled: bool = Field(
        default=True,
        description=(
            "Retry failed notifications in the background with exponential backoff. "
            "Recommended when routing through Tor where transient failures are common."
        ),
    )
    retry_max_attempts: int = Field(
        default=3,
        ge=1,
        le=10,
        description="Maximum number of retry attempts for a failed notification (1-10)",
    )
    retry_base_delay: float = Field(
        default=5.0,
        ge=1.0,
        le=60.0,
        description=(
            "Base delay in seconds before the first retry (1-60). "
            "Subsequent retries double this delay (exponential backoff)."
        ),
    )
Attributes
check_for_updates: bool = Field(default=False, description='Check GitHub for new releases and include version info in summary notifications. PRIVACY WARNING: This polls the GitHub API (api.github.com) each summary interval. The request is routed through Tor when use_tor is enabled, but GitHub will still see the Tor exit node IP. Opt-in only.') class-attribute instance-attribute
component_name: str = Field(default='', description="Component name in notification titles (e.g., 'Maker', 'Taker'). Usually set programmatically by each component.") class-attribute instance-attribute
enabled: bool = Field(default=False, description='Enable notifications (requires urls to be set)') class-attribute instance-attribute
include_amounts: bool = Field(default=True, description='Include amounts in notifications') class-attribute instance-attribute
include_nick: bool = Field(default=True, description='Include peer nicks in notifications') class-attribute instance-attribute
include_txids: bool = Field(default=False, description='Include transaction IDs in notifications (privacy risk)') class-attribute instance-attribute
notify_all_disconnect: bool = Field(default=True, description='Notify when ALL directory servers are disconnected (critical)') class-attribute instance-attribute
notify_coinjoin_complete: bool = Field(default=True, description='Notify on CoinJoin complete') class-attribute instance-attribute
notify_coinjoin_failed: bool = Field(default=True, description='Notify on CoinJoin failure') class-attribute instance-attribute
notify_coinjoin_start: bool = Field(default=True, description='Notify on CoinJoin start') class-attribute instance-attribute
notify_confirmed: bool = Field(default=True, description='Notify on confirmation') class-attribute instance-attribute
notify_disconnect: bool = Field(default=False, description='Notify on individual directory server disconnect/reconnect (noisy)') class-attribute instance-attribute
notify_fill: bool = Field(default=True, description='Notify on !fill requests') class-attribute instance-attribute
notify_mempool: bool = Field(default=True, description='Notify on mempool detection') class-attribute instance-attribute
notify_nick_change: bool = Field(default=True, description='Notify on nick change') class-attribute instance-attribute
notify_peer_events: bool = Field(default=False, description='Notify on peer connect/disconnect') class-attribute instance-attribute
notify_rate_limit: bool = Field(default=True, description='Notify on rate limit bans') class-attribute instance-attribute
notify_rejection: bool = Field(default=True, description='Notify on rejections') class-attribute instance-attribute
notify_signing: bool = Field(default=True, description='Notify on transaction signing') class-attribute instance-attribute
notify_startup: bool = Field(default=True, description='Notify on component startup') class-attribute instance-attribute
notify_summary: bool = Field(default=True, description='Send periodic summary notifications with CoinJoin stats') class-attribute instance-attribute
retry_base_delay: float = Field(default=5.0, ge=1.0, le=60.0, description='Base delay in seconds before the first retry (1-60). Subsequent retries double this delay (exponential backoff).') class-attribute instance-attribute
retry_enabled: bool = Field(default=True, description='Retry failed notifications in the background with exponential backoff. Recommended when routing through Tor where transient failures are common.') class-attribute instance-attribute
retry_max_attempts: int = Field(default=3, ge=1, le=10, description='Maximum number of retry attempts for a failed notification (1-10)') class-attribute instance-attribute
summary_interval_hours: int = Field(default=24, ge=1, le=168, description='Interval in hours between summary notifications (1-168). Common values: 24 (daily), 168 (weekly)') class-attribute instance-attribute
title_prefix: str = Field(default='JoinMarket NG', description='Prefix for notification titles') class-attribute instance-attribute
urls: list[str] = Field(default_factory=list, description='Apprise notification URLs (e.g., ["tgram://bottoken/ChatID", "gotify://hostname/token"])') class-attribute instance-attribute
use_tor: bool = Field(default=True, description='Route notifications through Tor SOCKS proxy') class-attribute instance-attribute

OrderbookWatcherSettings

Bases: BaseModel

Orderbook watcher specific settings.

Source code in jmcore/src/jmcore/settings.py 
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
class OrderbookWatcherSettings(BaseModel):
    """Orderbook watcher specific settings."""

    http_host: str = Field(
        default="0.0.0.0",
        description="HTTP server bind address",
    )
    http_port: int = Field(
        default=8000,
        ge=1,
        le=65535,
        description="HTTP server port",
    )
    update_interval: int = Field(
        default=60,
        ge=10,
        description="Update interval in seconds",
    )
    mempool_api_url: str = Field(
        default="http://mempopwcaqoi7z5xj5zplfdwk5bgzyl3hemx725d4a3agado6xtk3kqd.onion/api",
        description="Mempool API URL for transaction lookups",
    )
    mempool_web_url: str | None = Field(
        default="https://mempool.sgn.space",
        description="Mempool web URL for human-readable links",
    )
    uptime_grace_period: int = Field(
        default=60,
        ge=0,
        description="Grace period before tracking uptime",
    )
    max_message_size: int = Field(
        default=2097152,
        ge=1024,
        description="Maximum message size in bytes (2MB default)",
    )
    connection_timeout: float = Field(
        default=120.0,
        gt=0.0,
        description=(
            "Timeout in seconds for Tor SOCKS5 connections. Covers TCP handshake, "
            "SOCKS5 negotiation, Tor circuit building, and PoW solving."
        ),
    )
Attributes
connection_timeout: float = Field(default=120.0, gt=0.0, description='Timeout in seconds for Tor SOCKS5 connections. Covers TCP handshake, SOCKS5 negotiation, Tor circuit building, and PoW solving.') class-attribute instance-attribute
http_host: str = Field(default='0.0.0.0', description='HTTP server bind address') class-attribute instance-attribute
http_port: int = Field(default=8000, ge=1, le=65535, description='HTTP server port') class-attribute instance-attribute
max_message_size: int = Field(default=2097152, ge=1024, description='Maximum message size in bytes (2MB default)') class-attribute instance-attribute
mempool_api_url: str = Field(default='http://mempopwcaqoi7z5xj5zplfdwk5bgzyl3hemx725d4a3agado6xtk3kqd.onion/api', description='Mempool API URL for transaction lookups') class-attribute instance-attribute
mempool_web_url: str | None = Field(default='https://mempool.sgn.space', description='Mempool web URL for human-readable links') class-attribute instance-attribute
update_interval: int = Field(default=60, ge=10, description='Update interval in seconds') class-attribute instance-attribute
uptime_grace_period: int = Field(default=60, ge=0, description='Grace period before tracking uptime') class-attribute instance-attribute

TakerSettings

Bases: BaseModel

Taker-specific settings.

Source code in jmcore/src/jmcore/settings.py 
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
class TakerSettings(BaseModel):
    """Taker-specific settings."""

    counterparty_count: int = Field(
        default=10,
        ge=1,
        le=20,
        description="Number of makers to select for CoinJoin",
    )
    max_cj_fee_abs: int = Field(
        default=500,
        ge=0,
        description="Maximum absolute CoinJoin fee in satoshis",
    )
    max_cj_fee_rel: str = Field(
        default="0.001",
        description="Maximum relative CoinJoin fee (0.001 = 0.1%)",
    )
    tx_fee_factor: float = Field(
        default=3.0,
        ge=1.0,
        description="Multiply estimated fee by this factor",
    )
    fee_block_target: int | None = Field(
        default=None,
        ge=1,
        le=1008,
        description="Target blocks for fee estimation",
    )
    bondless_makers_allowance: float = Field(
        default=0.0,
        ge=0.0,
        le=1.0,
        description="Fraction of time to choose makers randomly",
    )
    bond_value_exponent: float = Field(
        default=1.3,
        gt=0.0,
        description="Exponent for fidelity bond value calculation",
    )
    bondless_require_zero_fee: bool = Field(
        default=True,
        description="Require zero absolute fee for bondless maker spots",
    )
    maker_timeout_sec: int = Field(
        default=60,
        ge=10,
        description="Timeout for maker responses",
    )
    order_wait_time: float = Field(
        default=120.0,
        ge=1.0,
        description=(
            "Seconds to wait for orderbook responses. Empirical testing shows 95th "
            "percentile response time over Tor is ~101s. Default 120s (with 20% buffer) "
            "captures ~95% of offers."
        ),
    )
    tx_broadcast: str = Field(
        default="random-peer",
        description="Broadcast policy: self, random-peer, multiple-peers, not-self",
    )
    broadcast_peer_count: int = Field(
        default=3,
        ge=1,
        description="Number of peers for multiple-peers broadcast",
    )
    minimum_makers: int = Field(
        default=1,
        ge=1,
        description="Minimum number of makers required",
    )
    rescan_interval_sec: int = Field(
        default=600,
        ge=60,
        description="Interval for periodic wallet rescans",
    )
Attributes
bond_value_exponent: float = Field(default=1.3, gt=0.0, description='Exponent for fidelity bond value calculation') class-attribute instance-attribute
bondless_makers_allowance: float = Field(default=0.0, ge=0.0, le=1.0, description='Fraction of time to choose makers randomly') class-attribute instance-attribute
bondless_require_zero_fee: bool = Field(default=True, description='Require zero absolute fee for bondless maker spots') class-attribute instance-attribute
broadcast_peer_count: int = Field(default=3, ge=1, description='Number of peers for multiple-peers broadcast') class-attribute instance-attribute
counterparty_count: int = Field(default=10, ge=1, le=20, description='Number of makers to select for CoinJoin') class-attribute instance-attribute
fee_block_target: int | None = Field(default=None, ge=1, le=1008, description='Target blocks for fee estimation') class-attribute instance-attribute
maker_timeout_sec: int = Field(default=60, ge=10, description='Timeout for maker responses') class-attribute instance-attribute
max_cj_fee_abs: int = Field(default=500, ge=0, description='Maximum absolute CoinJoin fee in satoshis') class-attribute instance-attribute
max_cj_fee_rel: str = Field(default='0.001', description='Maximum relative CoinJoin fee (0.001 = 0.1%)') class-attribute instance-attribute
minimum_makers: int = Field(default=1, ge=1, description='Minimum number of makers required') class-attribute instance-attribute
order_wait_time: float = Field(default=120.0, ge=1.0, description='Seconds to wait for orderbook responses. Empirical testing shows 95th percentile response time over Tor is ~101s. Default 120s (with 20% buffer) captures ~95% of offers.') class-attribute instance-attribute
rescan_interval_sec: int = Field(default=600, ge=60, description='Interval for periodic wallet rescans') class-attribute instance-attribute
tx_broadcast: str = Field(default='random-peer', description='Broadcast policy: self, random-peer, multiple-peers, not-self') class-attribute instance-attribute
tx_fee_factor: float = Field(default=3.0, ge=1.0, description='Multiply estimated fee by this factor') class-attribute instance-attribute

TomlConfigSettingsSource

Bases: PydanticBaseSettingsSource

Custom settings source that reads from a TOML config file.

The config file is expected at ~/.joinmarket-ng/config.toml or $JOINMARKET_DATA_DIR/config.toml if the environment variable is set.

Source code in jmcore/src/jmcore/settings.py 
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
class TomlConfigSettingsSource(PydanticBaseSettingsSource):
    """
    Custom settings source that reads from a TOML config file.

    The config file is expected at ~/.joinmarket-ng/config.toml or
    $JOINMARKET_DATA_DIR/config.toml if the environment variable is set.
    """

    def __init__(self, settings_cls: type[BaseSettings]) -> None:
        super().__init__(settings_cls)
        self._config: dict[str, Any] = {}
        self._load_config()

    def _get_config_path(self) -> Path:
        """Determine the config file path."""
        # Check for explicit config path in environment
        env_path = os.environ.get("JOINMARKET_CONFIG_FILE")
        if env_path:
            return Path(env_path)

        # Use data directory
        data_dir_env = os.environ.get("JOINMARKET_DATA_DIR")
        data_dir = Path(data_dir_env) if data_dir_env else Path.home() / ".joinmarket-ng"

        return data_dir / "config.toml"

    def _load_config(self) -> None:
        """Load configuration from TOML file."""
        config_path = self._get_config_path()

        if not config_path.exists():
            logger.debug(f"Config file not found at {config_path}, using defaults")
            return

        try:
            import tomllib

            with open(config_path, "rb") as f:
                self._config = tomllib.load(f)

            logger.info(f"Loaded config from {config_path}")
        except tomllib.TOMLDecodeError as e:
            logger.error(f"Invalid TOML syntax in config file {config_path}")
            logger.error(f"Error: {e}")
            logger.error("Please fix the syntax errors in your config file and try again.")
            logger.error(
                "Tip: Make sure section headers like [bitcoin], [tor], etc. are uncommented"
            )
            import sys

            sys.exit(1)
        except Exception as e:
            logger.error(f"Failed to load config from {config_path}: {e}")
            logger.error("Please check your config file and try again.")
            import sys

            sys.exit(1)

    def get_field_value(self, field: Any, field_name: str) -> tuple[Any, str, bool]:
        """Get field value from TOML config."""
        # Handle nested fields by looking up in nested dicts
        value = self._config.get(field_name)
        return value, field_name, value is not None

    def __call__(self) -> dict[str, Any]:
        """Return all config values as a flat dict for pydantic-settings."""
        return self._config
Functions
__call__() -> dict[str, Any]

Return all config values as a flat dict for pydantic-settings.

Source code in jmcore/src/jmcore/settings.py 
866
867
868
def __call__(self) -> dict[str, Any]:
    """Return all config values as a flat dict for pydantic-settings."""
    return self._config
__init__(settings_cls: type[BaseSettings]) -> None
Source code in jmcore/src/jmcore/settings.py 
810
811
812
813
def __init__(self, settings_cls: type[BaseSettings]) -> None:
    super().__init__(settings_cls)
    self._config: dict[str, Any] = {}
    self._load_config()
get_field_value(field: Any, field_name: str) -> tuple[Any, str, bool]

Get field value from TOML config.

Source code in jmcore/src/jmcore/settings.py 
860
861
862
863
864
def get_field_value(self, field: Any, field_name: str) -> tuple[Any, str, bool]:
    """Get field value from TOML config."""
    # Handle nested fields by looking up in nested dicts
    value = self._config.get(field_name)
    return value, field_name, value is not None

TorSettings

Bases: BaseModel

Tor proxy and control port configuration.

Source code in jmcore/src/jmcore/settings.py 
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
class TorSettings(BaseModel):
    """Tor proxy and control port configuration."""

    # SOCKS proxy settings
    socks_host: str = Field(
        default="127.0.0.1",
        description="Tor SOCKS5 proxy host",
    )
    socks_port: int = Field(
        default=9050,
        ge=1,
        le=65535,
        description="Tor SOCKS5 proxy port",
    )

    # Control port settings
    control_enabled: bool = Field(
        default=True,
        description="Enable Tor control port integration for ephemeral hidden services",
    )
    control_host: str = Field(
        default="127.0.0.1",
        description="Tor control port host",
    )
    control_port: int = Field(
        default=9051,
        ge=1,
        le=65535,
        description="Tor control port",
    )
    cookie_path: str | None = Field(
        default=None,
        description="Path to Tor cookie auth file",
    )
    password: SecretStr | None = Field(
        default=None,
        description="Tor control port password (use cookie auth instead if possible)",
    )

    # Hidden service target (for makers)
    target_host: str = Field(
        default="127.0.0.1",
        description="Target host for Tor hidden service (usually container name in Docker)",
    )

    # Stream isolation
    stream_isolation: bool = Field(
        default=True,
        description=(
            "Use SOCKS5 authentication to isolate different connection types "
            "onto separate Tor circuits.  This prevents traffic correlation "
            "between e.g. directory connections, peer connections, and "
            "notification traffic.  Requires IsolateSOCKSAuth on the Tor "
            "SocksPort (enabled by default)."
        ),
    )

    # Connection timeout
    connection_timeout: float = Field(
        default=120.0,
        gt=0.0,
        description=(
            "Timeout in seconds for Tor SOCKS5 connections. Covers TCP handshake, "
            "SOCKS5 negotiation, Tor circuit building, and PoW solving. "
            "Default 120s matches Tor's internal circuit timeout."
        ),
    )
Attributes
connection_timeout: float = Field(default=120.0, gt=0.0, description="Timeout in seconds for Tor SOCKS5 connections. Covers TCP handshake, SOCKS5 negotiation, Tor circuit building, and PoW solving. Default 120s matches Tor's internal circuit timeout.") class-attribute instance-attribute
control_enabled: bool = Field(default=True, description='Enable Tor control port integration for ephemeral hidden services') class-attribute instance-attribute
control_host: str = Field(default='127.0.0.1', description='Tor control port host') class-attribute instance-attribute
control_port: int = Field(default=9051, ge=1, le=65535, description='Tor control port') class-attribute instance-attribute
cookie_path: str | None = Field(default=None, description='Path to Tor cookie auth file') class-attribute instance-attribute
password: SecretStr | None = Field(default=None, description='Tor control port password (use cookie auth instead if possible)') class-attribute instance-attribute
socks_host: str = Field(default='127.0.0.1', description='Tor SOCKS5 proxy host') class-attribute instance-attribute
socks_port: int = Field(default=9050, ge=1, le=65535, description='Tor SOCKS5 proxy port') class-attribute instance-attribute
stream_isolation: bool = Field(default=True, description='Use SOCKS5 authentication to isolate different connection types onto separate Tor circuits. This prevents traffic correlation between e.g. directory connections, peer connections, and notification traffic. Requires IsolateSOCKSAuth on the Tor SocksPort (enabled by default).') class-attribute instance-attribute
target_host: str = Field(default='127.0.0.1', description='Target host for Tor hidden service (usually container name in Docker)') class-attribute instance-attribute

WalletSettings

Bases: BaseModel

Wallet configuration.

Source code in jmcore/src/jmcore/settings.py 
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
class WalletSettings(BaseModel):
    """Wallet configuration."""

    mixdepth_count: int = Field(
        default=5,
        ge=1,
        le=10,
        description="Number of mixdepths (privacy compartments)",
    )
    gap_limit: int = Field(
        default=20,
        ge=6,
        description="BIP44 gap limit for address scanning",
    )
    dust_threshold: int = Field(
        default=27300,
        ge=0,
        description="Dust threshold in satoshis",
    )
    smart_scan: bool = Field(
        default=True,
        description="Use smart scan for fast startup",
    )
    background_full_rescan: bool = Field(
        default=True,
        description="Run full blockchain rescan in background",
    )
    scan_lookback_blocks: int = Field(
        default=52560,
        ge=0,
        description="Blocks to look back for smart scan (~1 year default)",
    )
    scan_start_height: int | None = Field(
        default=None,
        ge=0,
        description="Explicit start height for initial scan (overrides scan_lookback_blocks if set)",
    )
    default_fee_block_target: int = Field(
        default=3,
        ge=1,
        le=1008,
        description="Default block target for fee estimation in wallet transactions",
    )
    mnemonic_file: str | None = Field(
        default=None,
        description="Default path to mnemonic file",
    )
    mnemonic_password: SecretStr | None = Field(
        default=None,
        description="Password for encrypted mnemonic file",
    )
    bip39_passphrase: SecretStr | None = Field(
        default=None,
        description="BIP39 passphrase (13th/25th word). For security, prefer BIP39_PASSPHRASE env var.",
    )
Attributes
background_full_rescan: bool = Field(default=True, description='Run full blockchain rescan in background') class-attribute instance-attribute
bip39_passphrase: SecretStr | None = Field(default=None, description='BIP39 passphrase (13th/25th word). For security, prefer BIP39_PASSPHRASE env var.') class-attribute instance-attribute
default_fee_block_target: int = Field(default=3, ge=1, le=1008, description='Default block target for fee estimation in wallet transactions') class-attribute instance-attribute
dust_threshold: int = Field(default=27300, ge=0, description='Dust threshold in satoshis') class-attribute instance-attribute
gap_limit: int = Field(default=20, ge=6, description='BIP44 gap limit for address scanning') class-attribute instance-attribute
mixdepth_count: int = Field(default=5, ge=1, le=10, description='Number of mixdepths (privacy compartments)') class-attribute instance-attribute
mnemonic_file: str | None = Field(default=None, description='Default path to mnemonic file') class-attribute instance-attribute
mnemonic_password: SecretStr | None = Field(default=None, description='Password for encrypted mnemonic file') class-attribute instance-attribute
scan_lookback_blocks: int = Field(default=52560, ge=0, description='Blocks to look back for smart scan (~1 year default)') class-attribute instance-attribute
scan_start_height: int | None = Field(default=None, ge=0, description='Explicit start height for initial scan (overrides scan_lookback_blocks if set)') class-attribute instance-attribute
smart_scan: bool = Field(default=True, description='Use smart scan for fast startup') class-attribute instance-attribute

Functions

ensure_config_file(data_dir: Path | None = None) -> Path

Ensure the config file exists, creating a template if it doesn't.

Args: data_dir: Optional data directory path. Uses default if not provided.

Returns: Path to the config file.

Source code in jmcore/src/jmcore/settings.py 
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
def ensure_config_file(data_dir: Path | None = None) -> Path:
    """
    Ensure the config file exists, creating a template if it doesn't.

    Args:
        data_dir: Optional data directory path. Uses default if not provided.

    Returns:
        Path to the config file.
    """
    if data_dir is None:
        data_dir = get_default_data_dir()

    config_path = data_dir / "config.toml"

    if not config_path.exists():
        logger.info(f"Creating config file template at {config_path}")
        data_dir.mkdir(parents=True, exist_ok=True)
        config_path.write_text(generate_config_template())

    return config_path

generate_config_template() -> str

Generate a config file template with all settings commented out.

This allows users to see all available settings with their defaults and descriptions, while only uncommenting what they want to change.

Source code in jmcore/src/jmcore/settings.py 
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
def generate_config_template() -> str:
    """
    Generate a config file template with all settings commented out.

    This allows users to see all available settings with their defaults
    and descriptions, while only uncommenting what they want to change.
    """
    lines: list[str] = []

    lines.append("# JoinMarket NG Configuration")
    lines.append("#")
    lines.append("# This file contains all available settings with their default values.")
    lines.append("# Settings are commented out by default - uncomment to override.")
    lines.append("#")
    lines.append("# Priority (highest to lowest):")
    lines.append("#   1. CLI arguments")
    lines.append("#   2. Environment variables")
    lines.append("#   3. This config file")
    lines.append("#   4. Built-in defaults")
    lines.append("#")
    lines.append("# Environment variables use uppercase with double underscore for nesting:")
    lines.append("#   TOR__SOCKS_HOST=127.0.0.1")
    lines.append("#   BITCOIN__RPC_URL=http://localhost:8332")
    lines.append("#")
    lines.append("")

    # Generate sections for each nested model
    def add_section(title: str, model_cls: type[BaseModel], prefix: str = "") -> None:
        lines.append(f"# {'=' * 60}")
        lines.append(f"# {title}")
        lines.append(f"# {'=' * 60}")
        lines.append(f"[{prefix}]" if prefix else "")
        lines.append("")

        for field_name, field_info in model_cls.model_fields.items():
            # Get description
            desc = field_info.description or ""
            if desc:
                lines.append(f"# {desc}")

            # Get default value
            default = field_info.default
            factory = field_info.default_factory
            if factory is not None:
                # default_factory can be Callable[[], Any] or Callable[[dict], Any]
                # We call with no args for the common case
                try:
                    default = factory()  # type: ignore[call-arg]
                except TypeError:
                    default = factory({})  # type: ignore[call-arg]

            # Format the value for TOML
            if isinstance(default, bool):
                value_str = str(default).lower()
            elif isinstance(default, str):
                value_str = f'"{default}"'
            elif isinstance(default, list):
                # For directory_servers, show example from defaults
                if field_name == "directory_servers" and prefix == "network_config":
                    lines.append("# Mainnet defaults (leave empty to use automatically):")
                    lines.append("# directory_servers = [")
                    for server in DEFAULT_DIRECTORY_SERVERS["mainnet"]:
                        lines.append(f'#   "{server}",')
                    lines.append("# ]")
                    lines.append("")
                    lines.append("# Signet defaults:")
                    lines.append("# directory_servers = [")
                    for server in DEFAULT_DIRECTORY_SERVERS["signet"]:
                        lines.append(f'#   "{server}",')
                    lines.append("# ]")
                    lines.append("")
                    continue
                value_str = "[]" if not default else str(default).replace("'", '"')
            elif isinstance(default, SecretStr):
                value_str = '""'
            elif default is None:
                # Skip None values with a comment
                lines.append(f"# {field_name} = ")
                lines.append("")
                continue
            elif hasattr(default, "value"):  # Enum - use string value
                value_str = f'"{default.value}"'
            else:
                value_str = str(default)

            lines.append(f"# {field_name} = {value_str}")
            lines.append("")

    # Data directory (top-level)
    lines.append("# Data directory for JoinMarket files")
    lines.append("# Defaults to ~/.joinmarket-ng or $JOINMARKET_DATA_DIR")
    lines.append("# data_dir = ")
    lines.append("")

    # Add all sections
    add_section("Tor Settings", TorSettings, "tor")
    add_section("Bitcoin Backend Settings", BitcoinSettings, "bitcoin")
    add_section("Network Settings", NetworkSettings, "network_config")
    add_section("Wallet Settings", WalletSettings, "wallet")
    add_section("Notification Settings", NotificationSettings, "notifications")
    add_section("Logging Settings", LoggingSettings, "logging")
    add_section("Maker Settings", MakerSettings, "maker")
    add_section("Taker Settings", TakerSettings, "taker")
    add_section("Directory Server Settings", DirectoryServerSettings, "directory_server")
    add_section("Orderbook Watcher Settings", OrderbookWatcherSettings, "orderbook_watcher")

    return "\n".join(lines)

get_config_path() -> Path

Get the path to the config file.

Source code in jmcore/src/jmcore/settings.py 
871
872
873
874
875
def get_config_path() -> Path:
    """Get the path to the config file."""
    data_dir_env = os.environ.get("JOINMARKET_DATA_DIR")
    data_dir = Path(data_dir_env) if data_dir_env else Path.home() / ".joinmarket-ng"
    return data_dir / "config.toml"

get_settings(**overrides: Any) -> JoinMarketSettings

Get the JoinMarket settings instance.

On first call, loads settings from all sources. Subsequent calls return the cached instance unless reset_settings() is called.

Args: **overrides: Optional settings overrides (highest priority)

Returns: JoinMarketSettings instance

Source code in jmcore/src/jmcore/settings.py 
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
def get_settings(**overrides: Any) -> JoinMarketSettings:
    """
    Get the JoinMarket settings instance.

    On first call, loads settings from all sources. Subsequent calls
    return the cached instance unless reset_settings() is called.

    Args:
        **overrides: Optional settings overrides (highest priority)

    Returns:
        JoinMarketSettings instance
    """
    global _settings
    if _settings is None or overrides:
        _settings = JoinMarketSettings(**overrides)
    return _settings

reset_settings() -> None

Reset the global settings instance (useful for testing).

Source code in jmcore/src/jmcore/settings.py 
1033
1034
1035
1036
def reset_settings() -> None:
    """Reset the global settings instance (useful for testing)."""
    global _settings
    _settings = None