xln

Tower Backup and Last-Resort Dispute Services

Index Status Mainnet Bar Protocol

This is the operational contract for the current tower service. Product copy should call the two capabilities:

The implementation may run both capabilities in one standalone tower daemon. They remain separate services in protocol terms: different lookup namespaces, different payloads, different failure modes, and different user promises.

Current Model

Encrypted backup

Last-resort dispute protection

Privacy Contract

Before breach:

On breach:

Daemon Surfaces

Public endpoints:

GET  /
GET  /healthz
GET  /api/tower/healthz
PUT  /api/tower/appointment
POST /api/tower/restore
GET  /api/tower/receipt/:lookupKey
POST /api/recovery/discover
POST /api/recovery/state
POST /api/recovery/complaint

Operator endpoints:

POST /api/watchtower/sweep
GET  /api/watchtower/actions/:lookupKey

Rules:

Configuration

Backup-only tower:

bun core/watchtower/standalone-server.ts \
  --host 0.0.0.0 \
  --port 9100 \
  --db data/watchtower \
  --max-bundles 3 \
  --quota-bytes 4194304

Backup plus last-resort disputer:

XLN_WATCHTOWER_PRIVATE_KEY=0x... \
XLN_WATCHTOWER_OPERATOR_TOKEN=... \
XLN_WATCHTOWER_ALLOWED_RPC_URLS=https://xln.finance/rpc,https://xln.finance/rpc2,https://xln.finance/rpc3,https://xln.finance/rpc4,https://xln.finance/rpc5,https://xln.finance/rpc6,https://xln.finance/rpc7,https://xln.finance/rpc8 \
bun core/watchtower/standalone-server.ts \
  --host 0.0.0.0 \
  --port 9100 \
  --db data/watchtower \
  --enable-last-resort-agent \
  --enable-operator-api \
  --sweep-interval-ms 30000

Defaults:

Deployment must allowlist the exact RPC URL advertised to wallets. A tower using a public upstream still rejects appointments naming an unlisted proxy. Sepolia includes https://sepolia.xln.finance/rpc explicitly; verify upload acceptance as well as tower health. The public P6 evidence records the rejected upload and the bounded configuration correction.

Restore Behavior

Restore is backup-only from the user’s perspective:

  1. Wallet derives the backup lookup key from runtimeId + runtimeSeed.
  2. Wallet asks configured towers for /api/tower/restore.
  3. Tower returns the latest snapshot and compatible journal tail.
  4. Wallet decrypts locally.
  5. Wallet validates bundle hash, lookup key, checkpoint hash, WAL tail, signer metadata, and restored runtime shape.
  6. Wallet re-announces restored gossip profiles so post-restore account routing can open accounts without a fresh hub discovery race.

The target restore SLA is under 1 minute. Current retention is designed for a small latest-state ring, not long-term audit history.

Dispute Sweep Behavior

For each latest delayed-last-resort appointment:

  1. Normalize and allowlist the RPC URL.
  2. Read current block and on-chain account state.
  3. Skip if no active dispute or before the last-resort window. Require a higher signed nonce, or an equal-nonce LEFT proposal overriding the active RIGHT.
  4. Find the matching DisputeStarted log for watched entity/counterentity.
  5. Use the event watchSeed to decrypt encryptedRemedy.
  6. Verify appointment sequence, proof nonce, proof body hash, chain id, depository, watched entity, counterentity, tower address, and final proofbody watchSeed.
  7. Submit watchtowerCounterDispute(...) to counter before timeout or finalize after timeout; an already registered counter is not resubmitted before expiry.
  8. Store an action receipt with submitted, skipped, or error.

The contract must enforce the last-resort delay. Tower policy alone is not a security boundary.

Edge Cases

Verification

Use the ladder, not a broad suite first.

L1 narrow:

bun test core/__tests__/storage/recovery/recovery-tower.test.ts
bun test core/__tests__/security/watchtower/watchtower-last-resort.test.ts
bun test tests/frontend/recovery/recovery-tower-config.test.ts

L2 targeted contract/RPC:

bun test core/__tests__/security/watchtower/watchtower-rpc-last-resort.test.ts

L2 browser restore:

E2E_BASE_URL=https://localhost:8080 \
E2E_API_BASE_URL=https://localhost:8080 \
E2E_RESET_BASE_URL=http://127.0.0.1:8082 \
PW_ONLY_CHROMIUM=1 PW_FAST=1 PW_VIDEO=off PW_TRACE=off PW_SCREENSHOT=only-on-failure \
bunx playwright test tests/e2e/recovery/e2e-watchtower-recovery.spec.ts --project=chromium

L3 gate:

bun run check

Mainnet cannot claim this subsystem ready unless encrypted backup restore and offline stale-dispute countering are both green.