Skip to content

BinancePositionReconciler

Recovers a degraded strategy automatically (openspec behaviour, Automatic Position Recovery, option A). A strategy that is degraded with position unknown or fee unknown gets the venue's holding as an absolute position event, only when it is the sole strategy that can move that symbol's asset on the account, and only when that holding is at or below the strategy's last known holding. In every other case nothing is published, the strategy stays degraded and the worker alerts.

A wrong absolute event makes a live strategy trade on wrong holdings with real money, so every unknown below ends in no event. The whole recovery, with the strategy's side, the alerts and the manual path, is on Position recovery.

flowchart LR
    BP["BinancePortfolio"] -->|account.snapshot| R["BinancePositionReconciler"]
    R -->|"ListWorkers, twice"| WM["WorkManager"]
    R -->|"positionstatus command"| S["Strategy"]
    R -->|"position.opened / closed, asof"| S
    R -.->|"status degraded, error event"| A(["alert"])

Where it lives, and why

Here, next to the account snapshot it reads. It observes and publishes an event; it holds no venue credential at all and no code path reaches a venue. It is not in execution-workers, whose workers hold order keys, and it depends on no executor.

One pass

Each account.snapshot starts a pass, so a recovery happens within one snapshotintervalseconds of BinancePortfolio (default 60 s) and needs no timer here.

  1. Who may trade on the account. ListWorkers returns every worker with its topics, config and secret references. Every worker is classified, in any state: a stopped strategy still owns what it bought.
    • An executor binds an sc.<id>.trading.order.submitted topic.
    • BinanceOrderUpdates, loaded from the org feed's package, is neither: it turns the venue's execution reports into the scenario's order events, places no order and holds no key. It is identified by its package URL only.
    • A trader is any other worker of a scenario (scenarioid config, or a topic under sc.<id>). Its symbols are its symbols config, which the strategy base enforces (an order outside it is withheld).
    • A scenario is on the account when every executor of it references the account's key (binanceapikey = this worker's accountsecret), off it when every executor references another key, and undetermined otherwise: no executor, a mix, or one with no key reference (a simulator, or a LiveExecutor on its host's environment credentials).
  2. Who is degraded. The positionstatus command asks each running trader of a scenario not off the account, in order with its inbox: decision-state owner, known symbols, unanswered, fee-unknown and working-order symbols, last activity per symbol. WorkManager keeps the reported status in the Runtime record only: ListWorkers does not return it, the lifecycle status event is sent once per change and may be missed or stale, and its detail is prose for people. The command is live, structured and read at the moment of the decision.
  3. List again. If the workers changed during the pass, nothing is decided.
  4. Decide, per degraded symbol. The first check that fails is the alert's reason.
  5. Save, then publish. The attempt is saved before the event leaves, so a crash publishes nothing and the next pass waits out the cooldown.

The checks

Check Refused when
On the account The strategy's scenario is not shown to be on it.
Declared It has no symbols, or the symbol is not in it.
Decision state The strategy does not own its record: the event would be lost on the next restore.
World Its portfolioworld is not the account's.
Exclusive Any trader not off the account, stopped or not, has no symbols, or trades a symbol with the asset as base or quote; or the strategy's own other symbols do. BTC_USDT and BTC_USDC share one balance of BTC, and so do BTC_USDT and ETH_BTC.
Fee asset The asset is a feeassets one and anything else trades: fees on any symbol may be paid in it.
Readable The symbol is no pair, or the snapshot does not list the asset. A zero listed is proof of flat, a missing asset is not.
Fresh The snapshot is older than maxsnapshotageseconds.
Still An order touching the asset is open on the venue, or the strategy has an order working.
Past the last activity The read began before the strategy's activation, or its last order or fill on the symbol, plus settleseconds.
Representable The holding does not fit the wire's 8 decimals or its range.
Capped The strategy has no last known holding of the symbol, or the venue holds more than it. See below.
Delivered The strategy does not bind the event's topic.
Attempts A recovery is in its cooldown (no alert), or maxattempts did not clear it (alert).

A list or read that fails, a snapshot of another account or world, and a malformed snapshot publish nothing and alert.

The cap

A venue reports a balance per asset and cannot say whose coins it holds. So a recovery may lower a holding to the venue's, never raise it. The last known holding is the one positionstatus reports, from the strategy's fold.

Why it is degraded Result
Fee unknown Recovers: the holding may exceed the account, and the venue's lowers it.
Unanswered order, venue at or below last known Recovers.
Unanswered buy that filled, venue above last known Refused, an operator sets it. The coins are the strategy's, but this worker cannot tell them from a deposit.
Saved record lost or unreadable Refused, always: there is no last known holding, even for a flat venue. An operator sets it.
Venue above last known for any other reason Refused.

An operator recovers a strategy by publishing an absolute position event without asof, which no cap applies to.

The event

sc.<scenarioid>.position.opened for a holding above zero, .closed at zero, with source: External, avgEntry: 0 and realizedPnL: 0: a spot balance has no cost basis, so a recovered position's average entry is not a price. The extension asof carries the read's time. A strategy folds such an event only while it is degraded for the symbol, with no order working, read after its activation and after the symbol's last order or fill, and at most its last known holding: the same checks, repeated at the fold, closing the gap between this worker's read and the strategy's next input. Anything else is dropped and logged, and the strategy stays degraded.

What it cannot see

Option A sets the strategy's holding to the venue's holding, up to the cap. It cannot tell whose coins those are:

  • Below the cap, foreign coins still count: a strategy that last knew 1, sold 0.6 unseen and shares the balance with a deposit of 0.4 recovers to 0.8. It can never gain more than it last knew.
  • A trader on the account outside WorkManager (the exchange UI, another cluster) is invisible, unless it has an order open at the snapshot.
  • A worker that sets symbols but is not on StrategyWorkerBase is believed.
  • An order submitted before the strategy lost its state and still in flight on an executor's inbox can execute after the read. Its fill is then not folded.
  • Whether the account pays fees in BNB: feeassets is config, not read from the venue.

Deploy

The testnet default is in config/config.json. Create it with accountsecret set to the reference your executor uses for binanceapikey. It takes no worker secrets. symbols must be set on every strategy of a scenario that may touch the account.