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.
- Who may trade on the account.
ListWorkersreturns 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.submittedtopic. - 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 (
scenarioidconfig, or a topic undersc.<id>). Its symbols are itssymbolsconfig, 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'saccountsecret), 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).
- An executor binds an
- Who is degraded. The
positionstatuscommand 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:ListWorkersdoes not return it, the lifecyclestatusevent is sent once per change and may be missed or stale, and itsdetailis prose for people. The command is live, structured and read at the moment of the decision. - List again. If the workers changed during the pass, nothing is decided.
- Decide, per degraded symbol. The first check that fails is the alert's reason.
- 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
symbolsbut is not onStrategyWorkerBaseis 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:
feeassetsis 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.