jmwalletd.routers.wallet

jmwalletd.routers.wallet

Wallet lifecycle and info endpoints.

Covers: getinfo, session, wallet/all, wallet/create, wallet/recover, wallet/{name}/unlock, wallet/{name}/lock, token refresh.

Attributes

router = APIRouter() module-attribute

Classes

Functions:

get_info() -> GetInfoResponse async

Return backend information.

Source code in jmwalletd/src/jmwalletd/routers/wallet.py

@router.get("/getinfo", operation_id="version")
async def get_info() -> GetInfoResponse:
    """Return backend information."""
    from jmcore.version import __version__

    return GetInfoResponse(version=__version__, backend="joinmarket-ng")

get_session(request: Request, state: DaemonState = Depends(get_daemon_state)) -> SessionResponse async

Heartbeat / status endpoint.

If an Authorization header is present, it is validated. An invalid token returns 401. A missing token is fine (unauthenticated access).

Source code in jmwalletd/src/jmwalletd/routers/wallet.py

@router.get("/session", operation_id="session")
async def get_session(
    request: Request,
    state: DaemonState = Depends(get_daemon_state),
) -> SessionResponse:
    """Heartbeat / status endpoint.

    If an Authorization header is present, it is validated. An invalid
    token returns 401. A missing token is fine (unauthenticated access).
    """
    token = get_optional_token(request)
    token_valid = False

    if token is not None:
        try:
            state.token_authority.verify_access(token)
            token_valid = True
        except pyjwt.InvalidTokenError as exc:
            raise InvalidToken(str(exc)) from exc

    # Bitcoin Core is the source of truth for rescan state: the in-memory
    # flag can go stale while Core keeps scanning server-side (issue #551).
    rescanning, _progress = await state.live_rescan_status()

    resp = SessionResponse(
        session=state.wallet_loaded,
        maker_running=state.maker_running,
        coinjoin_in_process=state.taker_running,
        wallet_name=state.wallet_name if state.wallet_loaded else "",
        rescanning=rescanning,
    )

    # Populate extra fields only when authenticated.
    if state.wallet_loaded and token_valid:
        resp.schedule = _get_running_tumble_schedule(state)
        resp.nickname = state.nickname
        taker = state._taker_ref
        resp.broadcast_policy = _broadcast_status_value(
            taker, "last_broadcast_policy", state.last_broadcast_policy
        )
        resp.broadcast_method = _broadcast_status_value(
            taker, "last_broadcast_method", state.last_broadcast_method
        )
        resp.broadcast_fallback_reason = _broadcast_status_value(
            taker,
            "last_broadcast_fallback_reason",
            state.last_broadcast_fallback_reason,
        )

        # Read offer_list directly from the running maker bot so that the
        # frontend receives it as soon as offers are created (the old path
        # through state.offer_list was unreachable because maker.start()
        # blocks until shutdown).
        offer_list = _get_offer_list_from_maker(state)
        resp.offer_list = offer_list if offer_list else state.offer_list

        try:
            backend = state.wallet_service.backend
            resp.block_height = await backend.get_block_height()
        except Exception:
            resp.block_height = None

        # Expose the underlying bitcoind descriptor wallet name for clients
        # (e.g. test setup / debugging tools) that need to query Bitcoin Core
        # directly. Only present when the active backend is a descriptor
        # wallet — other backends (Neutrino) leave this unset.
        try:
            backend = state.wallet_service.backend
            wallet_name_attr = getattr(backend, "wallet_name", None)
            if isinstance(wallet_name_attr, str) and wallet_name_attr:
                resp.descriptor_wallet_name = wallet_name_attr
        except Exception:
            resp.descriptor_wallet_name = None

    return resp

list_wallets(state: DaemonState = Depends(get_daemon_state)) -> ListWalletsResponse async

List available wallet files.

Source code in jmwalletd/src/jmwalletd/routers/wallet.py

@router.get("/wallet/all", operation_id="listwallets")
async def list_wallets(
    state: DaemonState = Depends(get_daemon_state),
) -> ListWalletsResponse:
    """List available wallet files."""
    return ListWalletsResponse(wallets=state.list_wallets())

token_refresh(body: TokenRequest, _auth: dict[str, Any] = Depends(require_auth_allow_expired), state: DaemonState = Depends(get_daemon_state)) -> TokenResponse async

Refresh the access/refresh token pair.

Source code in jmwalletd/src/jmwalletd/routers/wallet.py

@router.post("/token", operation_id="token")
async def token_refresh(
    body: TokenRequest,
    _auth: dict[str, Any] = Depends(require_auth_allow_expired),
    state: DaemonState = Depends(get_daemon_state),
) -> TokenResponse:
    """Refresh the access/refresh token pair."""
    if body.grant_type != "refresh_token":
        raise InvalidRequestFormat("Unsupported grant_type. Must be 'refresh_token'.")

    try:
        state.token_authority.verify_refresh(body.refresh_token)
    except pyjwt.InvalidTokenError as exc:
        logger.debug("Refresh token verification failed: {}", exc)
        raise InvalidToken(f"Invalid refresh token: {exc}") from exc

    tokens = state.token_authority.issue(state.wallet_name)

    return TokenResponse(
        walletname=state.wallet_name,
        token=tokens.token,
        token_type=tokens.token_type,
        expires_in=tokens.expires_in,
        scope=tokens.scope,
        refresh_token=tokens.refresh_token,
    )

wallet_create(body: CreateWalletRequest, state: DaemonState = Depends(get_daemon_state)) -> CreateWalletResponse async

Create a new wallet.

Source code in jmwalletd/src/jmwalletd/routers/wallet.py

@router.post("/wallet/create", status_code=201, operation_id="createwallet")
async def wallet_create(
    body: CreateWalletRequest,
    state: DaemonState = Depends(get_daemon_state),
) -> CreateWalletResponse:
    """Create a new wallet."""
    async with state.wallet_lifecycle_lock:
        if state.wallet_loaded:
            raise WalletAlreadyUnlocked()

        wallet_path = state.wallets_dir / body.walletname
        if wallet_path.exists():
            raise WalletAlreadyExists()

        try:
            wallet_service, seedphrase = await create_wallet(
                wallet_path=wallet_path,
                password=body.password,
                wallet_type=body.wallettype,
                data_dir=state.data_dir,
            )
        except FileExistsError as exc:
            raise WalletAlreadyExists() from exc
        except OSError as exc:
            raise LockExists(str(exc)) from exc
        except ValueError as exc:
            raise InvalidRequestFormat(str(exc)) from exc

        state.wallet_service = wallet_service
        state.wallet_mnemonic = seedphrase
        state.wallet_name = body.walletname
        state.wallet_password = body.password

        # A generated wallet has no pre-existing history to suppress, so monitoring
        # can become live without risking a readiness error after seed generation.
        state.start_tx_monitor(baseline_existing=False)
        await _require_tx_monitor_ready(state)

        tokens = state.token_authority.issue(body.walletname)

    return CreateWalletResponse(
        walletname=body.walletname,
        seedphrase=seedphrase,
        token=tokens.token,
        token_type=tokens.token_type,
        expires_in=tokens.expires_in,
        scope=tokens.scope,
        refresh_token=tokens.refresh_token,
    )

wallet_lock(walletname: str, _auth: dict[str, Any] = Depends(require_auth), _wallet: None = Depends(require_wallet_match), state: DaemonState = Depends(get_daemon_state)) -> LockWalletResponse async

Lock the current wallet and stop all services.

Source code in jmwalletd/src/jmwalletd/routers/wallet.py

@router.get("/wallet/{walletname}/lock", operation_id="lockwallet")
async def wallet_lock(
    walletname: str,
    _auth: dict[str, Any] = Depends(require_auth),
    _wallet: None = Depends(require_wallet_match),
    state: DaemonState = Depends(get_daemon_state),
) -> LockWalletResponse:
    """Lock the current wallet and stop all services."""
    async with state.wallet_lifecycle_lock:
        already_locked = await state._lock_wallet()
    return LockWalletResponse(walletname=walletname, already_locked=already_locked)

wallet_recover(body: RecoverWalletRequest, state: DaemonState = Depends(get_daemon_state)) -> CreateWalletResponse async

Recover a wallet from a seed phrase.

Source code in jmwalletd/src/jmwalletd/routers/wallet.py

@router.post("/wallet/recover", status_code=201, operation_id="recoverwallet")
async def wallet_recover(
    body: RecoverWalletRequest,
    state: DaemonState = Depends(get_daemon_state),
) -> CreateWalletResponse:
    """Recover a wallet from a seed phrase."""
    async with state.wallet_lifecycle_lock:
        if state.wallet_loaded:
            raise WalletAlreadyUnlocked()

        wallet_path = state.wallets_dir / body.walletname
        if wallet_path.exists():
            raise WalletAlreadyExists()

        try:
            wallet_service = await recover_wallet(
                wallet_path=wallet_path,
                password=body.password,
                wallet_type=body.wallettype,
                seedphrase=body.seedphrase,
                data_dir=state.data_dir,
                scan_range=body.scan_range,
            )
        except FileExistsError as exc:
            raise WalletAlreadyExists() from exc
        except OSError as exc:
            raise LockExists(str(exc)) from exc
        except ValueError as exc:
            raise InvalidRequestFormat(str(exc)) from exc

        state.wallet_service = wallet_service
        state.wallet_mnemonic = body.seedphrase
        state.wallet_name = body.walletname
        state.wallet_password = body.password

        state.start_tx_monitor()
        try:
            await _require_tx_monitor_ready(state, lock_on_failure=True)
        except BackendNotReady:
            # Recovery is a create operation. Remove the encrypted file so the
            # caller can retry the same request after a transient backend outage.
            try:
                wallet_path.unlink(missing_ok=True)
            except OSError:
                logger.error("Failed to roll back wallet recovery")
                logger.bind(sensitive=True).exception(
                    "Failed to roll back wallet recovery for {}", body.walletname
                )
            raise

        tokens = state.token_authority.issue(body.walletname)

    return CreateWalletResponse(
        walletname=body.walletname,
        seedphrase=body.seedphrase,
        token=tokens.token,
        token_type=tokens.token_type,
        expires_in=tokens.expires_in,
        scope=tokens.scope,
        refresh_token=tokens.refresh_token,
    )

wallet_unlock(walletname: WalletName, body: UnlockWalletRequest, state: DaemonState = Depends(get_daemon_state)) -> UnlockWalletResponse async

Unlock (decrypt) a wallet.

Source code in jmwalletd/src/jmwalletd/routers/wallet.py

@router.post("/wallet/{walletname}/unlock", operation_id="unlockwallet")
async def wallet_unlock(
    walletname: WalletName,
    body: UnlockWalletRequest,
    state: DaemonState = Depends(get_daemon_state),
) -> UnlockWalletResponse:
    """Unlock (decrypt) a wallet."""
    async with state.wallet_lifecycle_lock:
        wallet_path = state.wallets_dir / walletname
        if not wallet_path.exists():
            raise WalletNotFound()

        if state.unlock_retry_delay(walletname) > 0:
            raise UnlockBackoff()

        # If the same wallet is already unlocked, just verify password and re-issue tokens.
        if state.wallet_loaded and state.wallet_name == walletname:
            if body.password != state.wallet_password:
                state.record_unlock_failure(walletname)
                raise InvalidCredentials()
            state.reset_unlock_failures(walletname)
            await _require_tx_monitor_ready(state, lock_on_failure=True)
            # ``rotate_refresh=False``: a second unlock of the same wallet (another
            # tab/device, or a client re-running its unlock flow) must not
            # invalidate the refresh token already held by the first client.
            tokens = state.token_authority.issue(walletname, rotate_refresh=False)
            return UnlockWalletResponse(
                walletname=walletname,
                token=tokens.token,
                token_type=tokens.token_type,
                expires_in=tokens.expires_in,
                scope=tokens.scope,
                refresh_token=tokens.refresh_token,
            )

        # Authenticate a target wallet before mutating a different active
        # session. Opening a service early can conflict with its backend, so
        # verification deliberately only decrypts the wallet file here.
        if state.wallet_loaded:
            try:
                await verify_wallet_password(wallet_path=wallet_path, password=body.password)
            except ValueError as exc:
                state.record_unlock_failure(walletname)
                raise InvalidCredentials(str(exc)) from exc
            await state._lock_wallet()

        try:
            wallet_service, seedphrase = await open_wallet_with_mnemonic(
                wallet_path=wallet_path,
                password=body.password,
                data_dir=state.data_dir,
                sync_on_open=False,
            )
        except OSError as exc:
            raise LockExists(str(exc)) from exc
        except ValueError as exc:
            state.record_unlock_failure(walletname)
            raise InvalidCredentials(str(exc)) from exc

        state.reset_unlock_failures(walletname)
        state.wallet_service = wallet_service
        state.wallet_mnemonic = seedphrase
        state.wallet_name = walletname
        state.wallet_password = body.password

        # Kick off sync asynchronously so unlock returns immediately.
        if state._wallet_sync_task is not None and not state._wallet_sync_task.done():
            state._wallet_sync_task.cancel()
        state._wallet_sync_task = asyncio.create_task(_background_wallet_sync(state, walletname))

        # Start pushing WebSocket notifications for wallet transactions (issue #560).
        state.start_tx_monitor()
        await _require_tx_monitor_ready(state, lock_on_failure=True)

        tokens = state.token_authority.issue(walletname)

    return UnlockWalletResponse(
        walletname=walletname,
        token=tokens.token,
        token_type=tokens.token_type,
        expires_in=tokens.expires_in,
        scope=tokens.scope,
        refresh_token=tokens.refresh_token,
    )