jmwallet.cli.send

jmwallet.cli.send

Send transaction command.

Attributes

Classes

Functions:

send(destination: Annotated[str, typer.Argument(help='Destination address')], amount: Annotated[int, typer.Option('--amount', '-a', help='Amount in sats (0 for sweep; with --select-utxos, defaults to sweep)')] = 0, mnemonic_file: Annotated[Path | None, typer.Option('--mnemonic-file', '-f', envvar='MNEMONIC_FILE')] = None, prompt_bip39_passphrase: Annotated[bool, typer.Option('--prompt-bip39-passphrase', help='Prompt for BIP39 passphrase')] = False, mixdepth: Annotated[int | None, typer.Option('--mixdepth', '-m', help='Source mixdepth. Fixed-amount automatic sends use the highest funded mixdepth unless set explicitly; automatic sweeps require this option. With --select-utxos, it is derived from the selection unless set explicitly.')] = None, fee_rate: Annotated[float | None, typer.Option('--fee-rate', help='Manual fee rate in sat/vB (e.g. 1.5). Mutually exclusive with --block-target. Defaults to 3-block estimation.')] = None, block_target: Annotated[int | None, typer.Option('--block-target', help='Target blocks for fee estimation (1-1008). Defaults to 3.')] = None, network: Annotated[str | None, typer.Option('--network', '-n', help='Bitcoin network')] = None, backend_type: Annotated[str | None, typer.Option('--backend', '-b', help='Backend: descriptor_wallet | neutrino')] = None, rpc_url: Annotated[str | None, typer.Option('--rpc-url', envvar='BITCOIN_RPC_URL')] = None, neutrino_url: Annotated[str | None, typer.Option('--neutrino-url', envvar='NEUTRINO_URL')] = None, broadcast: Annotated[bool, typer.Option('--broadcast/--no-broadcast', help='Broadcast the transaction (use --no-broadcast to skip)')] = True, rbf: Annotated[bool, typer.Option('--rbf/--no-rbf', help='Signal BIP125 replace-by-fee (enabled by default)')] = True, yes: Annotated[bool, typer.Option('--yes', '-y', help='Skip confirmation prompt')] = False, select_utxos: Annotated[bool, typer.Option('--select-utxos', '-s', help='Interactively select UTXOs (fzf-like TUI)')] = False, input_utxo: Annotated[list[str] | None, typer.Option('--input-utxo', help='Explicit input UTXO as txid:vout (repeatable). Spends exactly the given UTXOs (also for sweeps) instead of auto-selecting; every UTXO must already be unfrozen and belong to --mixdepth. Mutually exclusive with --select-utxos.')] = None, allow_conflicts: Annotated[bool, typer.Option('--allow-conflicts', help='Allow replacement of named wallet inputs spent by a mempool transaction')] = False, data_dir: Annotated[Path | None, typer.Option('--data-dir', envvar='JOINMARKET_DATA_DIR', help='Data directory (default: ~/.joinmarket-ng or $JOINMARKET_DATA_DIR)')] = None, config_file: Annotated[Path | None, typer.Option('--config-file', envvar='JOINMARKET_CONFIG_FILE', help='Config file path (decoupled from data dir). Defaults to <data-dir>/config.toml')] = None, log_level: Annotated[str | None, typer.Option('--log-level', '-l', help='Log level')] = None) -> None

Send a simple transaction from wallet to an address.

Source code in jmwallet/src/jmwallet/cli/send.py

@app.command(no_args_is_help=True)
def send(
    destination: Annotated[str, typer.Argument(help="Destination address")],
    amount: Annotated[
        int,
        typer.Option(
            "--amount",
            "-a",
            help="Amount in sats (0 for sweep; with --select-utxos, defaults to sweep)",
        ),
    ] = 0,
    mnemonic_file: Annotated[
        Path | None, typer.Option("--mnemonic-file", "-f", envvar="MNEMONIC_FILE")
    ] = None,
    prompt_bip39_passphrase: Annotated[
        bool, typer.Option("--prompt-bip39-passphrase", help="Prompt for BIP39 passphrase")
    ] = False,
    mixdepth: Annotated[
        int | None,
        typer.Option(
            "--mixdepth",
            "-m",
            help="Source mixdepth. Fixed-amount automatic sends use the highest funded "
            "mixdepth unless set explicitly; automatic sweeps require this option. "
            "With --select-utxos, it is derived from the selection unless set explicitly.",
        ),
    ] = None,
    fee_rate: Annotated[
        float | None,
        typer.Option(
            "--fee-rate",
            help="Manual fee rate in sat/vB (e.g. 1.5). "
            "Mutually exclusive with --block-target. "
            "Defaults to 3-block estimation.",
        ),
    ] = None,
    block_target: Annotated[
        int | None,
        typer.Option(
            "--block-target",
            help="Target blocks for fee estimation (1-1008). Defaults to 3.",
        ),
    ] = None,
    network: Annotated[str | None, typer.Option("--network", "-n", help="Bitcoin network")] = None,
    backend_type: Annotated[
        str | None,
        typer.Option("--backend", "-b", help="Backend: descriptor_wallet | neutrino"),
    ] = None,
    rpc_url: Annotated[str | None, typer.Option("--rpc-url", envvar="BITCOIN_RPC_URL")] = None,
    neutrino_url: Annotated[
        str | None, typer.Option("--neutrino-url", envvar="NEUTRINO_URL")
    ] = None,
    broadcast: Annotated[
        bool,
        typer.Option(
            "--broadcast/--no-broadcast",
            help="Broadcast the transaction (use --no-broadcast to skip)",
        ),
    ] = True,
    rbf: Annotated[
        bool,
        typer.Option(
            "--rbf/--no-rbf",
            help="Signal BIP125 replace-by-fee (enabled by default)",
        ),
    ] = True,
    yes: Annotated[bool, typer.Option("--yes", "-y", help="Skip confirmation prompt")] = False,
    select_utxos: Annotated[
        bool,
        typer.Option(
            "--select-utxos",
            "-s",
            help="Interactively select UTXOs (fzf-like TUI)",
        ),
    ] = False,
    input_utxo: Annotated[
        list[str] | None,
        typer.Option(
            "--input-utxo",
            help="Explicit input UTXO as txid:vout (repeatable). Spends exactly "
            "the given UTXOs (also for sweeps) instead of auto-selecting; every "
            "UTXO must already be unfrozen and belong to --mixdepth. Mutually "
            "exclusive with --select-utxos.",
        ),
    ] = None,
    allow_conflicts: Annotated[
        bool,
        typer.Option(
            "--allow-conflicts",
            help="Allow replacement of named wallet inputs spent by a mempool transaction",
        ),
    ] = False,
    data_dir: Annotated[
        Path | None,
        typer.Option(
            "--data-dir",
            envvar="JOINMARKET_DATA_DIR",
            help="Data directory (default: ~/.joinmarket-ng or $JOINMARKET_DATA_DIR)",
        ),
    ] = None,
    config_file: Annotated[
        Path | None,
        typer.Option(
            "--config-file",
            envvar="JOINMARKET_CONFIG_FILE",
            help="Config file path (decoupled from data dir). Defaults to <data-dir>/config.toml",
        ),
    ] = None,
    log_level: Annotated[
        str | None,
        typer.Option("--log-level", "-l", help="Log level"),
    ] = None,
) -> None:
    """Send a simple transaction from wallet to an address."""
    settings = setup_cli(log_level, data_dir=data_dir, config_file=config_file)

    # Validate mutual exclusivity

    if fee_rate is not None and block_target is not None:
        logger.error("Cannot specify both --fee-rate and --block-target")
        raise typer.Exit(1)

    if select_utxos and input_utxo:
        logger.error("Cannot specify both --select-utxos and --input-utxo")
        raise typer.Exit(1)

    if allow_conflicts and not input_utxo:
        logger.error("--allow-conflicts requires at least one --input-utxo")
        raise typer.Exit(1)

    if amount == 0 and mixdepth is None and not select_utxos:
        logger.error("--mixdepth is required when sweeping (--amount 0)")
        raise typer.Exit(1)

    # Effective cap comes from settings (with hard-coded fallback). The same
    # cap is also enforced after backend fee estimation in _send_transaction
    # below, so the estimated path is protected too, not just the manual-rate
    # CLI path.
    max_fee_rate = settings.wallet.max_fee_rate_sat_vb

    if fee_rate is not None:
        if not math.isfinite(fee_rate) or fee_rate <= 0:
            logger.error("--fee-rate must be a finite number greater than 0")
            raise typer.Exit(1)
        if fee_rate > max_fee_rate:
            logger.error(
                f"--fee-rate {fee_rate:.2f} sat/vB exceeds safety maximum "
                f"({max_fee_rate:.0f} sat/vB)"
            )
            raise typer.Exit(1)

    try:
        resolved = resolve_mnemonic(
            settings,
            mnemonic_file=mnemonic_file,
            prompt_bip39_passphrase=prompt_bip39_passphrase,
        )
        if not resolved:
            raise ValueError("No mnemonic provided")
        resolved_mnemonic = resolved.mnemonic
        resolved_bip39_passphrase = resolved.bip39_passphrase
        resolved_creation_height = resolved.creation_height
    except (FileNotFoundError, ValueError) as e:
        logger.error(str(e))
        raise typer.Exit(1)

    # Resolve backend settings
    backend_settings = resolve_backend_settings(
        settings,
        network=network,
        backend_type=backend_type,
        rpc_url=rpc_url,
        neutrino_url=neutrino_url,
        data_dir=data_dir,
    )
    if allow_conflicts and backend_settings.backend_type != "descriptor_wallet":
        logger.error("--allow-conflicts is supported only with the descriptor_wallet backend")
        raise typer.Exit(1)

    # Use configured default block target if not specified
    if block_target is None and fee_rate is None:
        block_target = settings.wallet.default_fee_block_target

    asyncio.run(
        _send_transaction(
            resolved_mnemonic,
            destination,
            amount,
            mixdepth,
            fee_rate,
            block_target,
            backend_settings,
            broadcast,
            yes,
            select_utxos,
            resolved_bip39_passphrase,
            creation_height=resolved_creation_height,
            mnemonic_file=resolved.mnemonic_file,
            mixdepth_count=settings.wallet.mixdepth_count,
            max_fee_rate_sat_vb=max_fee_rate,
            max_sats_freeze_reuse=settings.wallet.max_sats_freeze_reuse,
            reconstruct_history=settings.wallet.reconstruct_history,
            input_utxos=input_utxo,
            allow_conflicts=allow_conflicts,
            rbf=rbf,
        )
    )