Skip to content

Add owner-only recovery controls for Lightning, Ambrosia, and device restart/shutdown #741

Description

@ca-ruz

Summary

Add owner/admin-only recovery controls for local deployments:

  • refresh/restart phoenixd Lightning backend;
  • restart Ambrosia backend/service;
  • reboot the device/OPI;
  • gracefully shut down the device/OPI.

These actions should help field operators recover from temporary service or Lightning state problems without SSH, while keeping the controls gated and auditable.

Context

Recent investigation suggests that repeated outgoing payment failures may have been resolved by a restart/reconnection/state refresh rather than by a phoenixd binary upgrade.

Ambrosia already has related Electron/service-management code:

  • electron/main.js handles services:restart.
  • electron/services/ServiceManager.js has restartService(serviceName).
  • electron/main.js has phoenixd:set-auto-liquidity, which can call serviceManager.restartService('phoenixd').
  • Settings UI already has auto-liquidity restart copy, but that is not a general payment recovery action.

The new recovery controls should be separate from auto-liquidity settings because changing liquidity configuration is not the same as recovering from a stuck/temporary outgoing payment issue.

Proposed Work

Add a protected recovery section with these actions:

  • Refresh Lightning: restart phoenixd only, when Ambrosia manages phoenixd locally.
  • Restart Ambrosia: restart only the Ambrosia backend/service.
  • Restart Device: reboot the OPI/device.
  • Shut Down Device: gracefully shut down the OPI/device.

Requirements:

  • owner/admin only;
  • not shown to cashier role by default;
  • confirmation modal for each action;
  • clear copy explaining impact;
  • disable actions while one is already in progress;
  • record audit event with actor/timestamp/action/result;
  • platform guard so actions are available only where supported;
  • hide or disable Lightning restart when using NWC or an external backend Ambrosia cannot restart;
  • after phoenixd restart, poll phoenixd health/getinfo/getbalance/listchannels;
  • after Ambrosia restart, show reconnect/progress state if the UI remains open.

UX Guidance

Avoid wording such as:

Fix phoenixd issue

Prefer operational wording:

Refresh Lightning backend

For Lightning refresh, explain:

This restarts the local phoenixd service. Pending Lightning payments may need time to settle. Use this when routing or temporary peer errors repeat.

For device reboot/shutdown, clearly state that the POS may be unavailable until the device is back online.

Acceptance Criteria

  • Owner/admin can restart managed phoenixd from Ambrosia.
  • Owner/admin can restart Ambrosia where supported.
  • Owner/admin can reboot and gracefully shut down the OPI/device where supported.
  • Cashier/non-admin cannot access these actions.
  • Unsupported environments show a clear unavailable state.
  • NWC/external Lightning backend does not show a misleading phoenixd restart action.
  • Each action requires confirmation and prevents duplicate execution.
  • Success/failure states are visible to the user.
  • Audit logs capture actor, timestamp, action, and result.
  • Tests cover permissions, confirmations, success, failure, unsupported environment, NWC/external backend, and duplicate action prevention.

Security Notes

These actions must not become unauthenticated local endpoints. They should require authenticated owner/admin permissions and should not be available from public/customer views.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions