unrip/PROOF.md

# Implementation Proof: NEAR Intents request creation and EURe-to-BTC taker flow

Status: open
Opened: 2026-04-12

## Target outcome
The repository must be able to create our own NEAR Intents EURe-to-BTC swap request from credited internal inventory, submit it through repo-owned code, and explain the full request lifecycle from preflight through settlement truth.

For each repo-created request the operator must be able to answer:
- which asset and amount we intended to spend
- which asset and minimum amount we expected to receive
- which signer, verifier contract, nonce, deadline, slippage, and idempotency key were used
- whether the request was drafted, blocked, submitted, accepted by relay, failed, awaiting settlement, not filled, or completed
- whether completed means durable inventory movement, not relay acceptance
- how much BTC was received and how much EURe was spent, if settlement is proven

## Why this is the next architecture test
The existing system can observe incoming NEAR Intents quote requests and respond as a solver or maker. That path has not produced fills at 1.49%, 0.99%, or 0.49% in recent live validation, and it cannot intentionally convert our EURe inventory into BTC.

The next false path would be manually moving funds or adding a button that submits opaque live requests without durable preflight, request, and settlement evidence. This turn is successful only if the system can create requests as a first-class, auditable repo-owned flow instead of treating live fund movement as an off-system action.

## Scope
- [I017] Repo-owned NEAR Intents request creation and EURe-to-BTC taker flow: create, sign, submit, and settle our own swap requests from credited inventory with truthful dashboard evidence. tags=intents,taker,execution,inventory,settlement
- Active venue only: NEAR Intents.
- Active direction: credited internal EURe to BTC.
- Use credited spendable internal inventory only. Pending funding remains non-spendable.
- Build the request path with dry-run/preflight first, then gated live submission.
- Actual live submission requires explicit operator control and must be recorded durably.

## Assumptions
- NEAR Intents exposes a supported request or quote publication method through the solver relay or another documented endpoint callable with our existing API key and verifier signer.
- The correct taker intent can be represented as a signed verifier token_diff payload or a documented request envelope whose semantics can be proven before live submission.
- Internal inventory snapshots are fresh enough to enforce spendable EURe and settlement deltas.
- BTC minimum receive can be derived from reference price plus explicit slippage or minimum-out policy.
- The user's intent is to build the capability to move EURe into BTC; live all-EURe execution remains behind an explicit final operator action in the repo-owned UI or API.

## Turn-shaping rules
- Do not manually move funds.
- Do not submit an all-EURe live request until repo-owned preflight, durable request logging, and settlement attribution are implemented and the operator explicitly triggers that live request.
- Do not use pending or uncredited EURe.
- Do not label relay acceptance as completed settlement.
- Do not hide slippage, minimum receive, deadline, nonce, signer, or request id.
- If the NEAR Intents request API cannot be verified from primary evidence or live dry-run behavior, stop and record the blocker instead of inventing a protocol.
- Keep maker quote-response logic intact unless the new taker flow proves it should be paused or separated.

## Non-goals
- No new venue.
- No external wallet or manual bridge action.
- No automatic recurring rebalancer.
- No realized net PnL claim without fee and cost attribution.
- No tax or accounting treatment.
- No broad multi-asset request builder beyond EURe-to-BTC.

## Required operator behavior

### Request preflight truth
Before submission, the operator must see:
- spendable EURe available
- requested EURe spend amount
- BTC reference price
- slippage or minimum-out rule
- expected BTC receive and minimum BTC receive
- deadline and nonce policy
- exact signer account and verifier contract
- whether this is dry-run only or live-submit capable

### Request lifecycle truth
For each repo-created request, the dashboard must show:
- request id, copyable
- idempotency key, copyable
- intent hash or relay request id if returned, copyable
- created_at, submitted_at, resolved_at if known
- state: draft, blocked, submitted, accepted_by_relay, failed, awaiting_settlement, not_filled, completed
- decisive reason for blocks, failures, or no-fill
- settlement evidence if completed

### Settlement truth
Completed requires durable asset movement evidence:
- EURe spend delta and BTC receive delta from inventory snapshots
- attribution method and caveat if heuristic
- submitted-only and relay-accepted rows remain separate from completed
- portfolio-vs-hold movement remains separate from realized trade PnL

## Semantic invariants
The implementation and tests must enforce at least:
- request submitted != completed
- relay accepted != settled inventory movement
- pending EURe cannot be spent
- insufficient spendable EURe blocks before signing or submission
- slippage and minimum-out must be explicit and persisted
- duplicate idempotency key cannot produce duplicate live submissions
- dry-run request cannot accidentally submit
- completed request rows require durable settlement evidence
- request-creation flow is distinct from incoming quote-response flow

## Definition of done
- The repo contains a verified NEAR Intents request-creation client or a recorded blocker proving the venue path is unavailable.
- A request preflight API computes amount, min-out, deadline, nonce policy, signer, verifier, and inventory checks from durable/current data.
- A gated live submission API exists only after preflight and records durable request, submission, and result events.
- The dashboard shows repo-created request rows separately from incoming quote-response rows, with copyable ids and lifecycle reasons.
- Settlement attribution handles repo-created requests without treating relay acceptance as completion.
- Regression tests cover request signing/envelope semantics, inventory blocks, dry-run safety, idempotency, submission failure, submitted-not-completed, and completed-only-with-settlement.
- The result is deployed through the repo workflow and validated against live service state.

## Validation evidence required
- Unit tests for request preflight and minimum-out/slippage math.
- Unit tests for signed request or request envelope construction using deterministic signer fixtures.
- Unit tests proving insufficient EURe blocks before signing/submission.
- Unit tests proving submitted/accepted requests do not count as completed without inventory deltas.
- Live dry-run/preflight evidence for current credited EURe inventory.
- If live submission is explicitly triggered, durable DB evidence for request, submission result, and later settlement or no-fill.
- Dashboard bootstrap evidence showing the new request lifecycle row with copyable ids and truthful state.

## Failure conditions
- Live funds are moved outside repo-owned code.
- A request is submitted without durable preflight and request records.
- The UI claims BTC was bought from relay acceptance alone.
- A dry-run path can submit.
- Pending funding is treated as spendable.
- The implementation cannot prove the NEAR Intents request API shape and still proceeds.

## Current real before this turn
- The repo has verifier signing for quote-response token_diff payloads.
- The repo has a solver relay websocket client and quote-response submission path.
- Credited internal BTC/EURe inventory is synced durably.
- Quote, decision, command, submission result, and outcome attribution records exist for incoming quote-response flow.
- The dashboard distinguishes submitted, not-filled, completed, rejected, and blocked rows for incoming quote responses.

## Deliberately not built by this proof
- General portfolio optimizer.
- Automatic all-in rebalancing loop.
- Fee-complete realized PnL.
- Venue-native terminal fill ingestion unless the request API provides it directly.