Compare commits
2 commits
e0dfd24a8b
...
c1a6024358
| Author | SHA1 | Date | |
|---|---|---|---|
|
c1a6024358 | ||
|
|
d513d387a8 |
6 changed files with 505 additions and 241 deletions
|
|
@ -13,6 +13,7 @@ Legacy note:
|
|||
- 2026-04-08: `cow-protocol-intent-based-venue-integration` closed with status `paused`. The CoW venue integration turn is paused after cluster investigation showed a real NEAR Intents ingest outage exposed a larger observability gap: the dashboard did not escalate stale quote flow or disconnected websocket clients, so runtime health and alerting need to be strengthened before adding a second venue.
|
||||
- 2026-04-08: `runtime-health-sentinel-alert-routing-and-anomaly-detection` closed with status `passed`. Runtime health is now sentinel-owned, stale truth no longer renders healthy, alert delivery and safe containment exist, and deployment automation rolls all repo-owned services from push.
|
||||
- 2026-04-09: `quote-lifecycle-truth-and-execution-explanation` closed with status `passed`. Live operator surfaces now derive quote lifecycle from durable evidence, distinguish strategy rejection from executor blocking and submission, expose copyable quote traces, and no longer overclaim submission as completion or asset movement.
|
||||
- 2026-04-10: `execution-outcome-truth-and-settled-attribution` closed with status `passed`. Deployed e0dfd24, validated 1 completed heuristic settlement-attributed trade, 6 inferred not-filled outcomes, submitted-only rows without asset deltas, and stable armed strategy/executor at the approved 1.49% threshold.
|
||||
## Research Turns
|
||||
|
||||
## Planning Events
|
||||
|
|
@ -27,3 +28,4 @@ Legacy note:
|
|||
- 2026-04-08: opened implementation turn `runtime-health-sentinel-alert-routing-and-anomaly-detection` from backlog items I020.
|
||||
- 2026-04-08: opened implementation turn `quote-lifecycle-truth-and-execution-explanation` from backlog items I021.
|
||||
- 2026-04-09: opened implementation turn `execution-outcome-truth-and-settled-attribution` from backlog items I017, I018.
|
||||
- 2026-04-10: opened implementation turn `settlement-aware-strategy-and-inventory-skew-controls` from backlog items I015.
|
||||
|
|
|
|||
|
|
@ -20,7 +20,6 @@ Rules:
|
|||
- [I012] Quotes and execution analytics workbench: live quote tape, quote count and volume windows, size-bucket distributions, oracle-deviation views, per-quote decision and execution trace, and matched-only filters.
|
||||
- [I013] Benchmark and PnL analytics: compare trade PnL versus mark-to-market, all-BTC hold, all-EURe hold, passive 50/50 hold, and hindsight trade quality against later benchmarks.
|
||||
|
||||
- [I015] (soon) Benchmark-aware strategy thresholds and inventory-skewed fees: compare live inventory against deposit-time hold and target BTC/EURe mix before quoting away preferred inventory. tags=strategy,inventory,pnl
|
||||
- [I016] (soon) Treasury cashflow and fee ledger: durably record deposits, withdrawals, bridge or network costs, and other non-trade cashflows so dashboard profit can move from mark-to-market to true net PnL. tags=pnl,fees,treasury
|
||||
## Research Candidates
|
||||
- [R001] Compare Kraken and CoinGecko drift and freshness for the assets needed to price the active pair.
|
||||
|
|
|
|||
|
|
@ -1,174 +1,142 @@
|
|||
# Implementation Turn: execution outcome truth and settled attribution
|
||||
# Implementation Turn: settlement-aware strategy and inventory-skew controls
|
||||
|
||||
Status: open
|
||||
Opened: 2026-04-09
|
||||
Opened: 2026-04-10
|
||||
|
||||
## Goal
|
||||
Make the live BTC/EURe quote path more real by durably linking submission, downstream outcome, and settled inventory attribution so the dashboard can distinguish completion from submission and show real post-trade movement where available.
|
||||
Use quote outcome truth, live inventory, and benchmark hold comparisons to make strategy thresholds and side selection explicit so the system trades only when evidence says the execution opportunity is worth changing inventory.
|
||||
|
||||
## Selected backlog items
|
||||
- [I017] Per-trade realized attribution: link each successful trade to actual settled inventory deltas and attributable costs so the system can report realized net contribution per trade instead of only expected edge.
|
||||
- [I018] Quote-to-outcome and markout analytics: link quote, response, decision, execution result, and settlement, then store later reference-price markouts to measure adverse selection and quote quality.
|
||||
- [I015] Benchmark-aware strategy thresholds and inventory-skewed fees: compare live inventory against deposit-time hold and target BTC/EURe mix before quoting away preferred inventory. tags=strategy,inventory,pnl
|
||||
|
||||
## Design rules
|
||||
- Treat downstream outcome and settlement truth as part of the same shared evidence path, not separate dashboard decoration.
|
||||
- Preserve the current turn’s semantic boundary: submission is still non-terminal.
|
||||
- Store explicit linkage and attribution records instead of recomputing ad hoc joins differently across pages.
|
||||
- If a linkage is heuristic, store the heuristic and expose uncertainty.
|
||||
- Keep the first implementation narrow to the active pair and current venue.
|
||||
- Keep the approved base threshold at `1.49%`.
|
||||
- Keep notional limits unchanged unless separately approved.
|
||||
- Treat inventory policy as strategy evidence, not as profitability truth.
|
||||
- Keep submitted, not-filled, and completed outcome counts semantically separate.
|
||||
- Store enough fields on each decision to replay why the strategy approved or rejected a quote.
|
||||
|
||||
## Problem statement for this turn
|
||||
The repository now explains why a quote was rejected, blocked, or submitted, but it still does not fully explain what happened after submission:
|
||||
- terminal outcome truth is absent or disconnected
|
||||
- recent submission tables are still quote-term oriented rather than settlement oriented
|
||||
- completed and realized labels cannot yet be proven from repo-owned durable records
|
||||
- later analytics such as markout and realized contribution have no canonical per-quote linkage record
|
||||
## Problem statement
|
||||
The current system can now say whether submitted quotes became linked asset movement, inferred not-fills, or are still submitted-only. The strategy still mostly answers a simpler question: does raw reference edge clear the threshold and is source inventory available?
|
||||
|
||||
This turn must therefore improve:
|
||||
- downstream outcome ingestion or linkage
|
||||
- quote-to-outcome storage
|
||||
- settlement attribution storage
|
||||
- operator rendering of completed versus submission-only rows
|
||||
That is not enough for a real operator workflow. A quote that clears raw edge may still sell down scarce inventory, worsen the BTC/EURe mix, or repeat a side with poor recent outcome evidence. Conversely, a quote with the same raw edge may be more desirable if it moves inventory toward target.
|
||||
|
||||
## Required evidence model
|
||||
Add one repo-owned quote outcome and attribution model with at least:
|
||||
- `quote_id`
|
||||
- `decision_id`
|
||||
- `command_id`
|
||||
- `execution_result_status`
|
||||
- `outcome_status`
|
||||
- `outcome_observed_at`
|
||||
- `outcome_source`
|
||||
- `attribution_status`
|
||||
- `attributed_inventory_delta`
|
||||
- `attribution_method`
|
||||
- `markout_reference_price` where implemented
|
||||
|
||||
Suggested vocabulary:
|
||||
- outcome states:
|
||||
- `submitted`
|
||||
- `awaiting_outcome`
|
||||
- `not_filled`
|
||||
- `completed`
|
||||
- attribution states:
|
||||
- `unattributed`
|
||||
- `heuristic_match`
|
||||
- `linked_settlement`
|
||||
This turn should make that policy explicit and visible.
|
||||
|
||||
## Backend changes
|
||||
|
||||
### 1. Add durable outcome linkage
|
||||
- inspect available downstream event sources, solver relay data, inventory movement evidence, and existing history tables
|
||||
- add a durable record or derived snapshot that links a submitted quote to later terminal outcome when possible
|
||||
- preserve source timestamps and raw evidence pointers
|
||||
### 1. Define strategy inventory policy
|
||||
- Add repo-owned config for target BTC value share and tolerance band.
|
||||
- Use current spendable BTC/EURe inventory plus latest reference price to compute current value mix.
|
||||
- For a candidate quote, compute projected post-trade mix using the proposed maker-side asset deltas.
|
||||
- Classify direction as `improves_inventory`, `within_band`, or `worsens_inventory`.
|
||||
- Keep policy disabled or neutral if required inputs are missing, with a visible reason.
|
||||
|
||||
### 2. Add durable settlement attribution
|
||||
- link completed quote outcomes to later inventory movement for the active assets
|
||||
- store both raw units and formatted operator values
|
||||
- track whether the attribution is exact or heuristic
|
||||
- do not report net realized contribution unless costs are explicitly present
|
||||
### 2. Compute effective threshold
|
||||
- Keep `base_threshold_pct = 1.49`.
|
||||
- Add an explicit `effective_threshold_pct` to each decision.
|
||||
- If inventory direction worsens target skew, require extra edge or reject with `inventory_skew_worsens`.
|
||||
- If inventory direction improves target skew, do not lower below the approved base threshold unless the user separately approves it.
|
||||
- Store the adjustment components separately from the final threshold.
|
||||
|
||||
### 3. Extend dashboard bootstrap models
|
||||
- expose recent quote outcome rows with terminal evidence where available
|
||||
- expose settled attribution separately from submitted quote terms
|
||||
- ensure summary metrics count completed outcomes and submission-only rows separately
|
||||
### 3. Add outcome-confidence inputs
|
||||
- Aggregate recent quote outcomes by side over a small explicit window.
|
||||
- Count submitted, not-filled, completed-heuristic, and completed-linked separately.
|
||||
- Do not count submitted as completion.
|
||||
- If outcome confidence affects threshold or reason, store the exact counts and window on the decision.
|
||||
|
||||
### 4. Prepare markout support on the same linkage path
|
||||
- if implemented in this turn, compute later reference-price markout from the linked quote or completion timestamp
|
||||
- store it in a way that cannot be confused with realized settlement contribution
|
||||
### 4. Extend durable decision payloads
|
||||
Each strategy decision should include:
|
||||
- `base_threshold_pct`
|
||||
- `effective_threshold_pct`
|
||||
- `threshold_adjustments`
|
||||
- `inventory_policy`
|
||||
- `inventory_skew_before`
|
||||
- `inventory_skew_after`
|
||||
- `inventory_direction`
|
||||
- `outcome_confidence`
|
||||
- `decision_reason`
|
||||
|
||||
### 5. Dashboard aggregation
|
||||
- Show base threshold and effective threshold on recent strategy/lifecycle rows.
|
||||
- Show inventory direction and decisive policy reason.
|
||||
- Keep quote ids copyable and full lifecycle reason visible.
|
||||
- Add a compact strategy policy panel with current target mix, current mix, and recent outcome counts.
|
||||
|
||||
## UI changes
|
||||
|
||||
### Strategy page
|
||||
- extend lifecycle rows so submitted paths can become `Awaiting outcome`, `Not filled`, or `Completed`
|
||||
- show linked outcome reason and settlement attribution state
|
||||
- keep quote, decision, and command trace ids visible
|
||||
- Add columns or row details for:
|
||||
- raw edge
|
||||
- base threshold
|
||||
- effective threshold
|
||||
- inventory direction
|
||||
- decisive reason
|
||||
- Keep successful-trade and lifecycle sections truthful from the previous turn.
|
||||
|
||||
### Funds page
|
||||
- separate:
|
||||
- recent submission terms
|
||||
- recent settled attribution
|
||||
- completed outcome ledger
|
||||
- if no settled attribution exists yet for a completed row, say that plainly
|
||||
- Keep `Portfolio vs simple hold` separate from realized PnL.
|
||||
- If inventory target mix is shown on Funds, label it as policy context, not profit.
|
||||
|
||||
### Summary language
|
||||
- introduce distinct labels for:
|
||||
- recent submissions
|
||||
- recent completed outcomes
|
||||
- recent settled attributions
|
||||
- never reuse one metric for all three concepts
|
||||
### System page
|
||||
- Surface strategy policy config and freshness only if it is directly useful for operator validation.
|
||||
|
||||
## Edge cases
|
||||
- submitted row with no later evidence:
|
||||
render as `Submitted` or `Awaiting outcome`
|
||||
- explicit expiry or non-fill evidence:
|
||||
render as `Not filled`
|
||||
- completed outcome with no attributable inventory delta yet:
|
||||
render completion truthfully, but mark attribution as missing
|
||||
- inventory movement with no unambiguous quote match:
|
||||
keep unattributed and do not silently assign
|
||||
- multiple near-simultaneous quotes in the same direction:
|
||||
require explicit or recorded heuristic linkage before claiming settlement
|
||||
- Missing price: reject or defer with `reference_price_unavailable`.
|
||||
- Missing inventory: reject or defer with `inventory_unavailable`.
|
||||
- Candidate quote has unsupported assets: reject with `unsupported_pair`.
|
||||
- Source inventory is insufficient: keep `insufficient_inventory`, not `inventory_skew_worsens`.
|
||||
- Quote improves skew but does not clear base threshold: reject with a reason that says raw edge failed base threshold.
|
||||
- Recent outcomes are all submitted-only: outcome confidence is unknown, not good.
|
||||
- Recent movement is heuristic: count separately from linked terminal settlement.
|
||||
|
||||
## Concrete implementation order
|
||||
|
||||
### Phase 1. Discover and define outcome sources
|
||||
- inspect current relay, executor, and inventory evidence
|
||||
- document what fields can carry downstream outcome and settlement linkage
|
||||
- define exact versus heuristic attribution rules
|
||||
### Phase 1. Model and tests
|
||||
- Add pure helper functions for inventory value mix, projected post-trade mix, direction classification, and effective threshold.
|
||||
- Add tests for improving, neutral, and worsening inventory directions.
|
||||
- Add tests that threshold never drops below `1.49`.
|
||||
|
||||
### Phase 2. Implement durable outcome and attribution records
|
||||
- add storage or derived records for linked outcomes
|
||||
- add storage or derived records for settlement attribution
|
||||
- preserve raw references and timestamps
|
||||
### Phase 2. Strategy integration
|
||||
- Wire helpers into `src/core/strategy.mjs` and `src/apps/strategy-engine.mjs`.
|
||||
- Extend emitted decision payloads with policy fields.
|
||||
- Preserve existing execution command shape unless size-limiting is implemented.
|
||||
|
||||
### Phase 3. Update dashboard aggregation
|
||||
- join recent lifecycle rows to outcome and attribution records
|
||||
- split summary metrics and ledgers by evidence strength
|
||||
- keep submission-only rows clearly non-terminal
|
||||
### Phase 3. Outcome-confidence integration
|
||||
- Load or derive recent outcome counts from existing quote outcome records where the strategy process can access them.
|
||||
- If direct DB access from strategy is too invasive, expose counts only on the dashboard in this turn and record that strategy-side outcome adjustment remains fake.
|
||||
- Add regression tests for submitted-only counts.
|
||||
|
||||
### Phase 4. Validate on live data
|
||||
- prove at least one recent row remains submission-only
|
||||
- prove blocked and rejected rows remain distinct
|
||||
- prove a completed or non-fill row appears only with durable linked evidence
|
||||
- prove settled attribution is shown only when actual linked movement exists
|
||||
### Phase 4. Operator surfaces
|
||||
- Update dashboard bootstrap and Strategy page to render the new policy fields.
|
||||
- Ensure no operator-facing `Actionable` label returns.
|
||||
- Ensure no submitted-only row is described as completed or successful.
|
||||
|
||||
### Phase 5. Deploy and validate
|
||||
- Run targeted tests plus full `npm test`.
|
||||
- Build the dashboard bundle.
|
||||
- Commit with required proof body.
|
||||
- Push to `forgejo/main`.
|
||||
- Validate rollout image, strategy state, executor state, dashboard bootstrap, and at least one recent decision carrying inventory-policy fields.
|
||||
|
||||
## Test plan
|
||||
- unit tests for outcome linkage:
|
||||
- submitted with no outcome
|
||||
- submitted with non-fill outcome
|
||||
- submitted with completed outcome
|
||||
- unit tests for attribution:
|
||||
- completed with linked settlement
|
||||
- completed without settlement yet
|
||||
- ambiguous movement remains unattributed
|
||||
- negative semantic tests:
|
||||
- submission-only rows must not render completion
|
||||
- markout must not be labeled realized
|
||||
- quote terms must not be labeled settled asset delta
|
||||
- dashboard bootstrap tests for:
|
||||
- separated summary metrics
|
||||
- completed rows carrying explicit outcome evidence
|
||||
- unattributed rows staying plainly unattributed
|
||||
- Unit tests for inventory-skew direction.
|
||||
- Unit tests for effective threshold calculation.
|
||||
- Unit tests for missing inputs and insufficient inventory reason precedence.
|
||||
- Dashboard tests for base/effective threshold rendering.
|
||||
- Negative tests:
|
||||
- submitted-only outcome count does not improve fill confidence
|
||||
- inventory-skew comparison is not labeled realized PnL
|
||||
- threshold below `1.49` is rejected or clamped unless explicitly configured in a test-only override
|
||||
|
||||
## Validation checklist against the proof
|
||||
- recent rows separate submitted, awaiting, not-filled, and completed where evidence exists
|
||||
- completed rows show explicit outcome linkage
|
||||
- settled attribution is visible and clearly sourced
|
||||
- submission-only rows still do not claim completion or realized movement
|
||||
- remaining uncertainty is named plainly
|
||||
- Live strategy `/state` shows decisions with inventory-policy fields.
|
||||
- Dashboard Strategy page can explain a quote that passed raw edge but was withheld or size-limited by inventory policy.
|
||||
- Dashboard Strategy page can explain a quote that improves inventory and clears base threshold.
|
||||
- Executor remains armed if it was armed before deployment.
|
||||
- The repo still deploys fully from push without manual cluster reconciliation.
|
||||
|
||||
## Failure modes to plan for
|
||||
- linking the wrong inventory movement to a quote
|
||||
- mistaking inventory rebalance or treasury movement for trade settlement
|
||||
- rendering completed from incomplete venue evidence
|
||||
- blending markout and realized attribution into one metric
|
||||
- introducing hidden heuristics without storing them
|
||||
|
||||
## Truth review checklist for this turn
|
||||
For every outcome or attribution field:
|
||||
- what exact durable event or snapshot backs it
|
||||
- how is the quote linked to it
|
||||
- is the linkage exact or heuristic
|
||||
- what wording would overclaim certainty
|
||||
- what regression test prevents that overclaim from returning
|
||||
## Known fakes allowed at start of this turn
|
||||
- Realized net PnL remains unavailable without fee/cost attribution.
|
||||
- Venue-native terminal fill events remain unavailable.
|
||||
- Outcome-confidence may be dashboard-only if strategy DB access is not justified in the implementation.
|
||||
|
|
|
|||
189
PROOF.md
189
PROOF.md
|
|
@ -1,138 +1,121 @@
|
|||
# Implementation Proof: execution outcome truth and settled attribution
|
||||
# Implementation Proof: settlement-aware strategy and inventory-skew controls
|
||||
|
||||
Status: open
|
||||
Opened: 2026-04-09
|
||||
Opened: 2026-04-10
|
||||
|
||||
## Target outcome
|
||||
This turn proves that `unrip` can move recent quote rows past submission-only evidence and into durable downstream outcome truth.
|
||||
The strategy should stop behaving like a one-dimensional edge filter and start making inventory-aware choices that are explainable from durable data.
|
||||
|
||||
For the live NEAR Intents BTC/EURe system, the operator must be able to answer:
|
||||
- was the quote merely submitted
|
||||
- did the venue later complete or not fill it
|
||||
- what settled inventory delta, if any, was actually observed afterward
|
||||
- what part of the post-trade change is still inferred versus durably linked
|
||||
For each live BTC/EURe quote the operator must be able to answer:
|
||||
- whether the quote was attractive on raw reference edge
|
||||
- whether trading that side improves or worsens the current inventory skew
|
||||
- whether the threshold used for that quote was the base threshold or an inventory-adjusted threshold
|
||||
- whether recent settlement outcomes support or weaken confidence in submitting more quotes on that side
|
||||
- why the strategy withheld, approved, or size-limited the quote
|
||||
|
||||
## Why this is a meaningful architecture test
|
||||
The previous turn fixed an overclaiming dashboard, but it also exposed the next hard truth gap:
|
||||
- `submitted` is now shown truthfully as non-terminal evidence
|
||||
- downstream completion and non-fill states are still mostly absent from durable repo-owned data
|
||||
- recent asset-term tables still describe submitted quote terms, not settled inventory truth
|
||||
- realized attribution is still fake because quote response success is not the same thing as completed asset movement
|
||||
## Why this is the next architecture test
|
||||
The previous turn made submission, not-fill, and settlement-attributed completion visible. It proved that the repo can now distinguish accepted quote responses from actual asset movement.
|
||||
|
||||
That means the system is now honest about the gap, but the gap still exists. This turn is where the shared history path must become more real again.
|
||||
The next false path is strategy behavior that ignores that truth:
|
||||
- a quote may clear the raw 1.49% edge but move inventory further away from the preferred BTC/EURe mix
|
||||
- the opposite side may be blocked by inventory, stale price, or poor recent fill evidence
|
||||
- portfolio-vs-hold movement is still not realized trade PnL and must not be used as if it were
|
||||
- simply lowering the edge threshold further would be risk widening without proof
|
||||
|
||||
## Hypothesis
|
||||
`unrip` becomes materially more trustworthy if it durably links:
|
||||
- quote
|
||||
- strategy decision
|
||||
- execute command
|
||||
- executor submission result
|
||||
- downstream venue or relay outcome where available
|
||||
- later settled inventory deltas attributable to that quote
|
||||
|
||||
The turn passes only if the operator can distinguish submission from later outcome and can inspect a recent completed path with explicit settled attribution instead of implied completion.
|
||||
This turn is successful only if strategy decisions become reproducible from explicit edge, inventory-skew, and settlement-outcome inputs.
|
||||
|
||||
## Scope
|
||||
- [I017] Per-trade realized attribution: link each successful trade to actual settled inventory deltas and attributable costs so the system can report realized net contribution per trade instead of only expected edge.
|
||||
- [I018] Quote-to-outcome and markout analytics: link quote, response, decision, execution result, and settlement, then store later reference-price markouts to measure adverse selection and quote quality.
|
||||
- Focus on the active NEAR Intents BTC/EURe venue and the repo-owned path already in production.
|
||||
- Cover recent rows first; historical backfill is secondary unless required to prove the live path.
|
||||
- [I015] Benchmark-aware strategy thresholds and inventory-skewed fees: compare live inventory against deposit-time hold and target BTC/EURe mix before quoting away preferred inventory.
|
||||
- Active venue and pair only: NEAR Intents BTC/EURe.
|
||||
- Preserve the approved base edge threshold of `1.49%` unless the user explicitly approves a different value.
|
||||
- Preserve the current max notional unless the user explicitly approves a different value.
|
||||
- Use existing durable portfolio metrics, inventory snapshots, reference prices, decisions, commands, execution results, and quote outcome attributions.
|
||||
|
||||
## Assumptions
|
||||
- The venue or relay emits enough downstream identifiers or status surfaces to link at least some submitted quotes to later terminal outcomes.
|
||||
- Inventory snapshots and durable history can support quote-to-settlement attribution for the active pair, even if the first version uses a narrow matching heuristic.
|
||||
- Some rows will still remain unattributed or partially inferred; the UI and stored records must say that plainly.
|
||||
- This turn should prioritize truthful linkage and settlement evidence over broad analytics polish.
|
||||
- The current BTC/EURe inventory mix has a preferred target or policy that can be encoded with repo-owned config.
|
||||
- The first inventory policy can be simple and explicit, for example target BTC value percentage plus a tolerance band.
|
||||
- Quote outcome records are good enough to compute side-level recent submission, not-fill, and completion counts, while remaining honest about heuristic settlement attribution.
|
||||
- Benchmark comparisons can guide strategy but are not realized PnL.
|
||||
|
||||
## Turn-shaping rules
|
||||
- `submitted` remains non-terminal evidence.
|
||||
- `completed`, `not filled`, `settled`, `realized`, and `asset delta` are forbidden unless backed by a durable linked record representing that fact.
|
||||
- If settlement attribution is heuristic rather than exact, the stored attribution record and operator surface must say so explicitly.
|
||||
- Do not build a broad analytics suite before the quote-to-outcome path is durably linked.
|
||||
- Prefer one repo-owned outcome and attribution model reused by storage, dashboard, and later analytics.
|
||||
- Do not lower `STRATEGY_GROSS_THRESHOLD_PCT` below `1.49` in this turn without explicit user approval.
|
||||
- Do not increase `STRATEGY_MAX_NOTIONAL_EURE` in this turn without explicit user approval.
|
||||
- Do not add live funds or move funds.
|
||||
- Do not claim inventory-skew benefit as realized profit.
|
||||
- Do not hide a base-threshold pass behind a generic rejection; expose the decisive strategy reason.
|
||||
- If recent outcome confidence is used, show the window and counts behind it.
|
||||
|
||||
## Non-goals
|
||||
- No new venue integration.
|
||||
- No generalized PnL accounting for all treasury cashflows.
|
||||
- No broad historical backfill project unless needed to prove current-path linkage.
|
||||
- No strategy changes beyond what is required to preserve truthful lifecycle and attribution semantics.
|
||||
- No new treasury fee ledger.
|
||||
- No generalized optimizer or ML strategy.
|
||||
- No broad backtesting workbench.
|
||||
- No tax, accounting, or realized net PnL claims.
|
||||
- No automatic funding, withdrawal, or treasury rebalancing.
|
||||
|
||||
## Required operator behavior
|
||||
|
||||
### Outcome truth
|
||||
For a recent submitted quote, the dashboard must be able to render one of:
|
||||
- `Submitted`
|
||||
- `Awaiting outcome`
|
||||
- `Not filled`
|
||||
- `Completed`
|
||||
### Strategy threshold truth
|
||||
Every recent strategy decision must expose:
|
||||
- base threshold
|
||||
- effective threshold
|
||||
- inventory adjustment, if any
|
||||
- outcome-confidence adjustment, if any
|
||||
- final decisive reason
|
||||
|
||||
The label must be driven by the strongest durable evidence currently stored.
|
||||
### Inventory-skew truth
|
||||
For every quote decision the dashboard must show:
|
||||
- current BTC and EURe spendable value
|
||||
- target BTC/EURe value mix or configured policy
|
||||
- current skew versus target
|
||||
- whether the proposed trade moves inventory toward or away from target
|
||||
|
||||
### Settlement truth
|
||||
For a recent completed quote, the operator must be able to inspect:
|
||||
- quote id
|
||||
- decision id
|
||||
- command id
|
||||
- executor result id or submission timestamp
|
||||
- linked terminal outcome evidence
|
||||
- linked settled asset delta or explicitly missing settled delta
|
||||
|
||||
### Attribution truth
|
||||
If the system reports realized contribution, it must be derived from:
|
||||
- linked settled asset movement
|
||||
- explicit attributable costs where available
|
||||
|
||||
If costs or full settlement are missing, the system must not claim net realized truth.
|
||||
|
||||
### Markout truth
|
||||
If markout is stored for completed or submitted rows, it must:
|
||||
- be clearly labeled as later reference-price comparison
|
||||
- remain separate from realized settlement attribution
|
||||
### Outcome-confidence truth
|
||||
If recent quote outcomes influence approval or threshold:
|
||||
- submitted-only rows must not count as completed
|
||||
- not-filled rows must be separate from strategy rejections and executor blocks
|
||||
- heuristic completed rows must be counted as heuristic, not venue-terminal fills
|
||||
|
||||
## Semantic invariants
|
||||
The implementation and tests must enforce at least:
|
||||
- `submitted != completed`
|
||||
- `completed` requires linked terminal outcome evidence
|
||||
- settled asset delta requires linked settlement evidence, not quote terms
|
||||
- markout is not realized PnL
|
||||
- unattributed inventory movement must not be silently assigned to a quote
|
||||
- `submitted` outcome evidence cannot improve fill-confidence as if completed
|
||||
- inventory-skew improvement is not realized PnL
|
||||
- base edge and effective edge must both be visible when they differ
|
||||
- insufficient inventory remains distinct from inventory-skew rejection
|
||||
- strategy rejection remains distinct from executor blocking
|
||||
- no threshold lower than `1.49%` is deployed without explicit approval
|
||||
|
||||
## Definition of done
|
||||
- A durable quote outcome link exists from submission to later outcome where available.
|
||||
- The repo stores an explicit per-quote outcome or attribution record for the active path.
|
||||
- The dashboard can show at least one recent path as `Completed` only when durable linked evidence supports it.
|
||||
- The dashboard can show non-fill or still-awaiting paths truthfully where that evidence exists.
|
||||
- Recent settled asset delta or explicit lack of attribution is visible per completed row.
|
||||
- Submission-term tables and summaries do not overclaim settled truth.
|
||||
- Regression tests cover the negative semantic boundaries above.
|
||||
- Strategy decisions include explicit inventory-skew inputs and effective threshold fields.
|
||||
- The strategy can approve, reject, or size-limit a quote based on inventory direction with a decisive reason.
|
||||
- Dashboard lifecycle or strategy rows show raw edge, effective threshold, skew direction, and decisive reason.
|
||||
- Recent outcome counts are available to the strategy or dashboard without treating submission-only rows as fills.
|
||||
- Regression tests cover inventory-skew direction, threshold adjustment, and the negative semantic invariants.
|
||||
- The result is deployed through the repo workflow and validated against live service state and dashboard bootstrap data.
|
||||
|
||||
## Validation evidence required
|
||||
- direct evidence from deployed dashboard or bootstrap payload that recent rows separate `Submitted`, `Blocked`, `Rejected`, `Not filled`, and `Completed` when the evidence exists
|
||||
- direct evidence that a completed row shows linked settled attribution rather than quote terms alone
|
||||
- direct evidence that a submission-only row still does not claim completion or realized asset movement
|
||||
- automated test evidence for quote-to-outcome linkage
|
||||
- automated test evidence for settlement attribution boundaries
|
||||
- Automated tests for strategy decisions that pass raw edge but fail inventory-skew policy.
|
||||
- Automated tests for strategy decisions where inventory improvement lowers friction or preserves the base threshold without lowering below `1.49%`.
|
||||
- Automated tests proving submitted-only outcomes do not improve completion confidence.
|
||||
- Live dashboard or `/state` evidence showing strategy decisions with base threshold, effective threshold, inventory skew, and decisive reason.
|
||||
- Live evidence that strategy and executor remain armed after deployment if they were armed before rollout.
|
||||
|
||||
## Failure conditions
|
||||
- the system still cannot represent downstream terminal outcome beyond submission
|
||||
- any UI or backend surface claims completion from submission-only evidence
|
||||
- settled asset delta is still derived from quoted terms rather than linked settlement evidence
|
||||
- markout or later reference comparison is presented as realized PnL
|
||||
- outcome attribution silently guesses across ambiguous rows without recording uncertainty
|
||||
- The strategy still emits only `actionable` or `insufficient_inventory` without inventory-policy evidence.
|
||||
- The dashboard cannot explain why a raw-edge quote was withheld by inventory policy.
|
||||
- A submitted quote is treated as a completed or successful trade in any strategy confidence calculation.
|
||||
- Benchmark or inventory-skew deltas are labeled as realized PnL.
|
||||
- The deployed threshold is lower than `1.49%` without explicit user approval.
|
||||
|
||||
## Current real before this turn
|
||||
- quote, decision, command, and execution submission result are durable
|
||||
- the dashboard now renders those stages truthfully
|
||||
- submission counts and recent submission terms are constrained to submission evidence
|
||||
- Live quote, decision, command, submission result, and quote outcome attribution records are durable.
|
||||
- The dashboard separates submitted, rejected, blocked, not-filled, and completed rows.
|
||||
- One historical quote is linked to a heuristic settled inventory delta.
|
||||
- Recent submitted-only rows are visible without claiming asset movement.
|
||||
- Portfolio-vs-simple-hold comparison is cash-flow adjusted and explicitly not realized PnL.
|
||||
|
||||
## Deliberately not built by this proof
|
||||
- full treasury fee ledger
|
||||
- generalized tax or accounting treatment
|
||||
- multi-venue settlement harmonization
|
||||
|
||||
## Prevention requirements for this proof
|
||||
- For every new `Completed`, `Not filled`, or realized attribution label:
|
||||
- what exact durable record backs it
|
||||
- what linkage key or heuristic connects it to the quote
|
||||
- what uncertainty remains
|
||||
- what regression test prevents future overclaiming
|
||||
- Full fee and cost attribution.
|
||||
- Venue-native terminal fill ingestion.
|
||||
- Automatic inventory rebalancing outside quote-response execution.
|
||||
- Broader research/backtest UI.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,174 @@
|
|||
# Implementation Turn: execution outcome truth and settled attribution
|
||||
|
||||
Status: open
|
||||
Opened: 2026-04-09
|
||||
|
||||
## Goal
|
||||
Make the live BTC/EURe quote path more real by durably linking submission, downstream outcome, and settled inventory attribution so the dashboard can distinguish completion from submission and show real post-trade movement where available.
|
||||
|
||||
## Selected backlog items
|
||||
- [I017] Per-trade realized attribution: link each successful trade to actual settled inventory deltas and attributable costs so the system can report realized net contribution per trade instead of only expected edge.
|
||||
- [I018] Quote-to-outcome and markout analytics: link quote, response, decision, execution result, and settlement, then store later reference-price markouts to measure adverse selection and quote quality.
|
||||
|
||||
## Design rules
|
||||
- Treat downstream outcome and settlement truth as part of the same shared evidence path, not separate dashboard decoration.
|
||||
- Preserve the current turn’s semantic boundary: submission is still non-terminal.
|
||||
- Store explicit linkage and attribution records instead of recomputing ad hoc joins differently across pages.
|
||||
- If a linkage is heuristic, store the heuristic and expose uncertainty.
|
||||
- Keep the first implementation narrow to the active pair and current venue.
|
||||
|
||||
## Problem statement for this turn
|
||||
The repository now explains why a quote was rejected, blocked, or submitted, but it still does not fully explain what happened after submission:
|
||||
- terminal outcome truth is absent or disconnected
|
||||
- recent submission tables are still quote-term oriented rather than settlement oriented
|
||||
- completed and realized labels cannot yet be proven from repo-owned durable records
|
||||
- later analytics such as markout and realized contribution have no canonical per-quote linkage record
|
||||
|
||||
This turn must therefore improve:
|
||||
- downstream outcome ingestion or linkage
|
||||
- quote-to-outcome storage
|
||||
- settlement attribution storage
|
||||
- operator rendering of completed versus submission-only rows
|
||||
|
||||
## Required evidence model
|
||||
Add one repo-owned quote outcome and attribution model with at least:
|
||||
- `quote_id`
|
||||
- `decision_id`
|
||||
- `command_id`
|
||||
- `execution_result_status`
|
||||
- `outcome_status`
|
||||
- `outcome_observed_at`
|
||||
- `outcome_source`
|
||||
- `attribution_status`
|
||||
- `attributed_inventory_delta`
|
||||
- `attribution_method`
|
||||
- `markout_reference_price` where implemented
|
||||
|
||||
Suggested vocabulary:
|
||||
- outcome states:
|
||||
- `submitted`
|
||||
- `awaiting_outcome`
|
||||
- `not_filled`
|
||||
- `completed`
|
||||
- attribution states:
|
||||
- `unattributed`
|
||||
- `heuristic_match`
|
||||
- `linked_settlement`
|
||||
|
||||
## Backend changes
|
||||
|
||||
### 1. Add durable outcome linkage
|
||||
- inspect available downstream event sources, solver relay data, inventory movement evidence, and existing history tables
|
||||
- add a durable record or derived snapshot that links a submitted quote to later terminal outcome when possible
|
||||
- preserve source timestamps and raw evidence pointers
|
||||
|
||||
### 2. Add durable settlement attribution
|
||||
- link completed quote outcomes to later inventory movement for the active assets
|
||||
- store both raw units and formatted operator values
|
||||
- track whether the attribution is exact or heuristic
|
||||
- do not report net realized contribution unless costs are explicitly present
|
||||
|
||||
### 3. Extend dashboard bootstrap models
|
||||
- expose recent quote outcome rows with terminal evidence where available
|
||||
- expose settled attribution separately from submitted quote terms
|
||||
- ensure summary metrics count completed outcomes and submission-only rows separately
|
||||
|
||||
### 4. Prepare markout support on the same linkage path
|
||||
- if implemented in this turn, compute later reference-price markout from the linked quote or completion timestamp
|
||||
- store it in a way that cannot be confused with realized settlement contribution
|
||||
|
||||
## UI changes
|
||||
|
||||
### Strategy page
|
||||
- extend lifecycle rows so submitted paths can become `Awaiting outcome`, `Not filled`, or `Completed`
|
||||
- show linked outcome reason and settlement attribution state
|
||||
- keep quote, decision, and command trace ids visible
|
||||
|
||||
### Funds page
|
||||
- separate:
|
||||
- recent submission terms
|
||||
- recent settled attribution
|
||||
- completed outcome ledger
|
||||
- if no settled attribution exists yet for a completed row, say that plainly
|
||||
|
||||
### Summary language
|
||||
- introduce distinct labels for:
|
||||
- recent submissions
|
||||
- recent completed outcomes
|
||||
- recent settled attributions
|
||||
- never reuse one metric for all three concepts
|
||||
|
||||
## Edge cases
|
||||
- submitted row with no later evidence:
|
||||
render as `Submitted` or `Awaiting outcome`
|
||||
- explicit expiry or non-fill evidence:
|
||||
render as `Not filled`
|
||||
- completed outcome with no attributable inventory delta yet:
|
||||
render completion truthfully, but mark attribution as missing
|
||||
- inventory movement with no unambiguous quote match:
|
||||
keep unattributed and do not silently assign
|
||||
- multiple near-simultaneous quotes in the same direction:
|
||||
require explicit or recorded heuristic linkage before claiming settlement
|
||||
|
||||
## Concrete implementation order
|
||||
|
||||
### Phase 1. Discover and define outcome sources
|
||||
- inspect current relay, executor, and inventory evidence
|
||||
- document what fields can carry downstream outcome and settlement linkage
|
||||
- define exact versus heuristic attribution rules
|
||||
|
||||
### Phase 2. Implement durable outcome and attribution records
|
||||
- add storage or derived records for linked outcomes
|
||||
- add storage or derived records for settlement attribution
|
||||
- preserve raw references and timestamps
|
||||
|
||||
### Phase 3. Update dashboard aggregation
|
||||
- join recent lifecycle rows to outcome and attribution records
|
||||
- split summary metrics and ledgers by evidence strength
|
||||
- keep submission-only rows clearly non-terminal
|
||||
|
||||
### Phase 4. Validate on live data
|
||||
- prove at least one recent row remains submission-only
|
||||
- prove blocked and rejected rows remain distinct
|
||||
- prove a completed or non-fill row appears only with durable linked evidence
|
||||
- prove settled attribution is shown only when actual linked movement exists
|
||||
|
||||
## Test plan
|
||||
- unit tests for outcome linkage:
|
||||
- submitted with no outcome
|
||||
- submitted with non-fill outcome
|
||||
- submitted with completed outcome
|
||||
- unit tests for attribution:
|
||||
- completed with linked settlement
|
||||
- completed without settlement yet
|
||||
- ambiguous movement remains unattributed
|
||||
- negative semantic tests:
|
||||
- submission-only rows must not render completion
|
||||
- markout must not be labeled realized
|
||||
- quote terms must not be labeled settled asset delta
|
||||
- dashboard bootstrap tests for:
|
||||
- separated summary metrics
|
||||
- completed rows carrying explicit outcome evidence
|
||||
- unattributed rows staying plainly unattributed
|
||||
|
||||
## Validation checklist against the proof
|
||||
- recent rows separate submitted, awaiting, not-filled, and completed where evidence exists
|
||||
- completed rows show explicit outcome linkage
|
||||
- settled attribution is visible and clearly sourced
|
||||
- submission-only rows still do not claim completion or realized movement
|
||||
- remaining uncertainty is named plainly
|
||||
|
||||
## Failure modes to plan for
|
||||
- linking the wrong inventory movement to a quote
|
||||
- mistaking inventory rebalance or treasury movement for trade settlement
|
||||
- rendering completed from incomplete venue evidence
|
||||
- blending markout and realized attribution into one metric
|
||||
- introducing hidden heuristics without storing them
|
||||
|
||||
## Truth review checklist for this turn
|
||||
For every outcome or attribution field:
|
||||
- what exact durable event or snapshot backs it
|
||||
- how is the quote linked to it
|
||||
- is the linkage exact or heuristic
|
||||
- what wording would overclaim certainty
|
||||
- what regression test prevents that overclaim from returning
|
||||
|
|
@ -0,0 +1,138 @@
|
|||
# Implementation Proof: execution outcome truth and settled attribution
|
||||
|
||||
Status: open
|
||||
Opened: 2026-04-09
|
||||
|
||||
## Target outcome
|
||||
This turn proves that `unrip` can move recent quote rows past submission-only evidence and into durable downstream outcome truth.
|
||||
|
||||
For the live NEAR Intents BTC/EURe system, the operator must be able to answer:
|
||||
- was the quote merely submitted
|
||||
- did the venue later complete or not fill it
|
||||
- what settled inventory delta, if any, was actually observed afterward
|
||||
- what part of the post-trade change is still inferred versus durably linked
|
||||
|
||||
## Why this is a meaningful architecture test
|
||||
The previous turn fixed an overclaiming dashboard, but it also exposed the next hard truth gap:
|
||||
- `submitted` is now shown truthfully as non-terminal evidence
|
||||
- downstream completion and non-fill states are still mostly absent from durable repo-owned data
|
||||
- recent asset-term tables still describe submitted quote terms, not settled inventory truth
|
||||
- realized attribution is still fake because quote response success is not the same thing as completed asset movement
|
||||
|
||||
That means the system is now honest about the gap, but the gap still exists. This turn is where the shared history path must become more real again.
|
||||
|
||||
## Hypothesis
|
||||
`unrip` becomes materially more trustworthy if it durably links:
|
||||
- quote
|
||||
- strategy decision
|
||||
- execute command
|
||||
- executor submission result
|
||||
- downstream venue or relay outcome where available
|
||||
- later settled inventory deltas attributable to that quote
|
||||
|
||||
The turn passes only if the operator can distinguish submission from later outcome and can inspect a recent completed path with explicit settled attribution instead of implied completion.
|
||||
|
||||
## Scope
|
||||
- [I017] Per-trade realized attribution: link each successful trade to actual settled inventory deltas and attributable costs so the system can report realized net contribution per trade instead of only expected edge.
|
||||
- [I018] Quote-to-outcome and markout analytics: link quote, response, decision, execution result, and settlement, then store later reference-price markouts to measure adverse selection and quote quality.
|
||||
- Focus on the active NEAR Intents BTC/EURe venue and the repo-owned path already in production.
|
||||
- Cover recent rows first; historical backfill is secondary unless required to prove the live path.
|
||||
|
||||
## Assumptions
|
||||
- The venue or relay emits enough downstream identifiers or status surfaces to link at least some submitted quotes to later terminal outcomes.
|
||||
- Inventory snapshots and durable history can support quote-to-settlement attribution for the active pair, even if the first version uses a narrow matching heuristic.
|
||||
- Some rows will still remain unattributed or partially inferred; the UI and stored records must say that plainly.
|
||||
- This turn should prioritize truthful linkage and settlement evidence over broad analytics polish.
|
||||
|
||||
## Turn-shaping rules
|
||||
- `submitted` remains non-terminal evidence.
|
||||
- `completed`, `not filled`, `settled`, `realized`, and `asset delta` are forbidden unless backed by a durable linked record representing that fact.
|
||||
- If settlement attribution is heuristic rather than exact, the stored attribution record and operator surface must say so explicitly.
|
||||
- Do not build a broad analytics suite before the quote-to-outcome path is durably linked.
|
||||
- Prefer one repo-owned outcome and attribution model reused by storage, dashboard, and later analytics.
|
||||
|
||||
## Non-goals
|
||||
- No new venue integration.
|
||||
- No generalized PnL accounting for all treasury cashflows.
|
||||
- No broad historical backfill project unless needed to prove current-path linkage.
|
||||
- No strategy changes beyond what is required to preserve truthful lifecycle and attribution semantics.
|
||||
|
||||
## Required operator behavior
|
||||
|
||||
### Outcome truth
|
||||
For a recent submitted quote, the dashboard must be able to render one of:
|
||||
- `Submitted`
|
||||
- `Awaiting outcome`
|
||||
- `Not filled`
|
||||
- `Completed`
|
||||
|
||||
The label must be driven by the strongest durable evidence currently stored.
|
||||
|
||||
### Settlement truth
|
||||
For a recent completed quote, the operator must be able to inspect:
|
||||
- quote id
|
||||
- decision id
|
||||
- command id
|
||||
- executor result id or submission timestamp
|
||||
- linked terminal outcome evidence
|
||||
- linked settled asset delta or explicitly missing settled delta
|
||||
|
||||
### Attribution truth
|
||||
If the system reports realized contribution, it must be derived from:
|
||||
- linked settled asset movement
|
||||
- explicit attributable costs where available
|
||||
|
||||
If costs or full settlement are missing, the system must not claim net realized truth.
|
||||
|
||||
### Markout truth
|
||||
If markout is stored for completed or submitted rows, it must:
|
||||
- be clearly labeled as later reference-price comparison
|
||||
- remain separate from realized settlement attribution
|
||||
|
||||
## Semantic invariants
|
||||
The implementation and tests must enforce at least:
|
||||
- `submitted != completed`
|
||||
- `completed` requires linked terminal outcome evidence
|
||||
- settled asset delta requires linked settlement evidence, not quote terms
|
||||
- markout is not realized PnL
|
||||
- unattributed inventory movement must not be silently assigned to a quote
|
||||
|
||||
## Definition of done
|
||||
- A durable quote outcome link exists from submission to later outcome where available.
|
||||
- The repo stores an explicit per-quote outcome or attribution record for the active path.
|
||||
- The dashboard can show at least one recent path as `Completed` only when durable linked evidence supports it.
|
||||
- The dashboard can show non-fill or still-awaiting paths truthfully where that evidence exists.
|
||||
- Recent settled asset delta or explicit lack of attribution is visible per completed row.
|
||||
- Submission-term tables and summaries do not overclaim settled truth.
|
||||
- Regression tests cover the negative semantic boundaries above.
|
||||
|
||||
## Validation evidence required
|
||||
- direct evidence from deployed dashboard or bootstrap payload that recent rows separate `Submitted`, `Blocked`, `Rejected`, `Not filled`, and `Completed` when the evidence exists
|
||||
- direct evidence that a completed row shows linked settled attribution rather than quote terms alone
|
||||
- direct evidence that a submission-only row still does not claim completion or realized asset movement
|
||||
- automated test evidence for quote-to-outcome linkage
|
||||
- automated test evidence for settlement attribution boundaries
|
||||
|
||||
## Failure conditions
|
||||
- the system still cannot represent downstream terminal outcome beyond submission
|
||||
- any UI or backend surface claims completion from submission-only evidence
|
||||
- settled asset delta is still derived from quoted terms rather than linked settlement evidence
|
||||
- markout or later reference comparison is presented as realized PnL
|
||||
- outcome attribution silently guesses across ambiguous rows without recording uncertainty
|
||||
|
||||
## Current real before this turn
|
||||
- quote, decision, command, and execution submission result are durable
|
||||
- the dashboard now renders those stages truthfully
|
||||
- submission counts and recent submission terms are constrained to submission evidence
|
||||
|
||||
## Deliberately not built by this proof
|
||||
- full treasury fee ledger
|
||||
- generalized tax or accounting treatment
|
||||
- multi-venue settlement harmonization
|
||||
|
||||
## Prevention requirements for this proof
|
||||
- For every new `Completed`, `Not filled`, or realized attribution label:
|
||||
- what exact durable record backs it
|
||||
- what linkage key or heuristic connects it to the quote
|
||||
- what uncertainty remains
|
||||
- what regression test prevents future overclaiming
|
||||
Loading…
Add table
Reference in a new issue