unrip/PROOF.md

# Implementation Proof: pre-credit funding visibility and operator alerts

Status: open
Opened: 2026-04-02

## Target outcome
The next turn is complete only when `unrip` can show operators the gap between "funds sent" and "funds spendable" with durable evidence, and can surface actionable alert state for the live loop without requiring log-diving or manual SQL every time something stalls.

This turn does not expand the trade hot path. It makes the existing live system more explainable and more operable.

## Hypothesis
`unrip` becomes materially safer to operate once it can:

1. observe configured funding handles before NEAR Intents credit
2. persist chain-level funding observations separately from spendable inventory
3. link pre-credit observations to later bridge and verifier credit where possible
4. emit durable alert state for stale prices, stale inventory, stuck funding, and failed execution submissions
5. expose that state through the same small control surfaces and PostgreSQL audit trail as the rest of the system

If pre-credit funding remains invisible, or alert state still lives only in transient logs, the live loop is still too opaque for routine funded operation.

## Scope
- [O003] Alerts for stale reference prices, stale inventory state, stuck funding actions, and failed executor submissions.
- [O004] Pre-credit funding visibility for slow chains: watch configured deposit addresses at chain level, track inbound transfers through mempool and on-chain confirmation before bridge credit, persist that state separately from spendable inventory, and alert operators when funding is seen, delayed, or stuck.

## Non-goals
- No new venue, pair, or strategy logic.
- No dashboard or polished UI.
- No automatic treasury actions or auto-refunding.
- No attempt to treat chain-level observations as spendable inventory.
- No change to the live execution arming model.

## Source-of-truth rule
Spendable inventory remains the existing truth:
- bridge and verifier credit determine spendable balances
- chain-level observations are visibility only

The new pre-credit path must never be allowed to make a direction tradable earlier than the verifier does.

## Required runtime behavior

### Funding visibility
- The system must know the currently active funding handles for BTC and EURe.
- For configured chains, it must watch those handles before NEAR Intents credit appears.
- It must distinguish at least these states where applicable:
  - `SEEN_UNCONFIRMED`
  - `SEEN_CONFIRMED`
  - `CREDIT_PENDING`
  - `CREDITED`
  - `FAILED_OR_STUCK`
- BTC is the must-prove chain because that is where live funding latency was operationally visible.
- Gnosis support may share the same event model even if its confirmation behavior is simpler.

### Alerts
- Alerts must be durable records, not only log lines.
- At minimum the system must raise and clear alert state for:
  - stale reference price
  - stale inventory snapshot
  - funding seen but not credited within policy
  - execution submission failure
- Alert transitions must be inspectable through HTTP state and PostgreSQL.

## Service expectations

### `liquidity-manager`
Must become the owner of chain-level funding observations because it already owns deposit handles and treasury state.

It must:
- refresh and retain active funding handles
- ingest chain-level funding observations
- reconcile them against bridge deposit state
- publish durable funding-observation records
- expose current per-handle funding state

It must not:
- mark funds spendable
- trade on pre-credit observations

### `inventory-sync`
May surface pre-credit funding context, but only under a clearly separate non-spendable field.

It must not:
- merge pre-credit observations into `spendable`

### `history-writer`
Must persist the new record families:
- funding observations
- alert events
- optionally current alert snapshots if the implementation separates events from state

### Alert evaluator
This may be a new small service or a tightly scoped extension of an existing one, but it must:
- evaluate staleness and stuck conditions from durable inputs
- emit durable alert events
- expose current alert state and the latest reasons

No broad orchestration or dashboard service should be introduced just to satisfy this proof.

## Required durable storage
PostgreSQL must store at least:
- funding observations before bridge credit
- alert events or alert snapshots
- enough timestamps and IDs to correlate:
  - funding handle
  - chain tx hash
  - later bridge tx hash or deposit record
  - resulting verifier credit snapshot when available

Kafka remains the event backbone.

## Required control surface
At minimum operators must be able to inspect:
- active funding handles
- latest pre-credit observations by handle
- confirmation depth or equivalent chain state when available
- whether a funding action is still pending credit
- current active alerts and their reasons

If a new alert service exists, it must expose:
- `GET /healthz`
- `GET /state`
- `POST /pause`
- `POST /resume`

## Definition of done
- The live cluster still runs the previously proven funded trade loop unchanged for spendable truth.
- At least one real funding handle is watched at chain level before bridge credit.
- For at least one real deposit path, the system records a pre-credit observation before or during confirmation and later records the credited state separately.
- PostgreSQL contains durable records for the pre-credit funding path and alert path.
- Operators can inspect current funding observations and current alerts through control APIs.
- A stale price or stale inventory condition can be induced safely and becomes a durable alert.
- A funding delay or manually injected stuck condition can be represented as a durable alert with explicit reason fields.
- A failed execution submission path is represented as an alert without inventing fake venue traffic.
- Tests cover:
  - pre-credit observations staying non-spendable
  - alert raise and clear transitions
  - correlation of funding observation to later credit when identifiers are available

## Failure conditions
- Funding observations exist only in logs and are not queryable later.
- Pre-credit observations leak into spendable inventory or strategy gating.
- Alerts cannot be queried as current state.
- The only proof of stuck funding is a human manually watching a block explorer.
- The implementation adds a dashboard shell without stronger runtime truth.

## Current real
- The first funded BTC/EURe live loop is already proven:
  - real quote ingest
  - real reference pricing
  - real credited inventory
  - real strategy decisions
  - real `quote_response` submissions
  - durable event chain in PostgreSQL
- Portfolio metrics are now durably computed and exposed, but alerting and pre-credit funding visibility are still incomplete.