Skip to content

feat: publish per-chain inventory and USDC corridor liq_ series [RAI-3087] #1679

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JuaniRios wants to merge 1 commit into
base: rai-2998-liq-metrics-inventory
Choose a base branch
from
+931 −36
Open

feat: publish per-chain inventory and USDC corridor liq_ series [RAI-3087] #1679

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions SPEC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1763,6 +1763,8 @@ instant), `liq_settings_*` and `liq_asset_*` for every symbol the primary chain
lists. An optional setting that is not configured has no series.
`liq_asset_extended_hours` is absent while counter trading is disabled.
`liq_settings_info{trading_mode}` is always empty, as it was in the exporter.
`liq_usdc_corridor_target{chain}` and `liq_usdc_corridor_deviation{chain}` give
the band of every configured USDC corridor, whatever the USDC mode.

Inventory is published each time the inventory write lock is released, from a
copy of the balances taken while the lock is held. Each copy is numbered in
Expand All @@ -1780,6 +1782,19 @@ inventory series stay unpublished until the next start and an error is logged.
0. The reserve is the configured cash reserve, else the gross broker cash
minus the available broker cash once the gross is read, else 0. It is absent
until withdrawable cash is read.
- `liq_equity_chain_available{symbol,chain}` and
`liq_usdc_chain_{available,inflight,ratio}{chain}` list each hedged chain's
vault separately. A chain whose vault no snapshot has read yet is left out: a
slot that only a fill, transfer or inflight created holds a delta from 0, not
a balance. A chain the config no longer hedges is left out too.
Comment thread
rain-marvin[bot] marked this conversation as resolved.
`liq_equity_chain_available` is in that chain's wrapped vault shares. Each
chain's wrapper has its own underlying-per-wrapped ratio, so the series must
not be summed across chains or added to broker shares. `liq_usdc_chain_ratio`
is that vault's available USDC over itself plus the gross broker cash. It is
absent until the gross broker cash is read and while both are 0: it is a
bot-only series, so the Values rule applies and no exporter sentinel stands
in. It is not the corridor's trigger ratio, which uses the vault total, in
flight included.

**Exception to financial-integrity rules.** Some ported series reproduce the
exporter's published sentinels: a ratio with a zero denominator is published as
Expand Down
5 changes: 5 additions & 0 deletions crates/config/src/rebalancing.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -214,6 +214,11 @@ impl UsdcCorridors {
self.by_chain.values().filter(move |_| enabled)
}

/// Every corridor table, in chain order, whatever the USDC mode.
pub fn configured(&self) -> impl Iterator<Item = &UsdcCorridorCtx> {
self.by_chain.values()
}

/// The corridors this build runs a cash transfer service for.
pub const fn served(&self) -> &BTreeSet<UsdcCorridor> {
&self.served
Expand Down
6 changes: 6 additions & 0 deletions docs/observability.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,13 +142,16 @@ second writer. A test scans `src/` for this.
| `liq_asset_counter_trading` | `symbol` | `settings` | `1` or `0`, every symbol the primary chain lists |
| `liq_asset_extended_hours` | `symbol` | `settings` | `1` or `0`; absent while counter trading is disabled |
| `liq_asset_rebalancing` | `symbol` | `settings` | `1` when the symbol starts new rebalancing operations |
| `liq_usdc_corridor_target` | `chain` | `settings` | every configured USDC corridor, whatever the USDC mode |
| `liq_usdc_corridor_deviation` | `chain` | `settings` | as above |
| `liq_equity_onchain_available` | `symbol` | `inventory` | primary chain vault |
| `liq_equity_offchain_available` | `symbol` | `inventory` | broker |
| `liq_equity_inflight_total` | `symbol` | `inventory` | primary chain vault plus broker in flight |
| `liq_equity_total` | `symbol` | `inventory` | onchain plus offchain plus in flight; excludes wallet tokens and other chains |
| `liq_equity_unwrapped` | `symbol` | `inventory` | Base wallet unwrapped tokens |
| `liq_equity_wrapped` | `symbol` | `inventory` | Base wallet wrapped tokens |
| `liq_equity_ratio` | `symbol` | `inventory` | onchain over onchain plus offchain; `0` when both are 0 |
| `liq_equity_chain_available` | `chain`, `symbol` | `inventory` | each chain vault a snapshot read, in its wrapped shares: never sum across chains or with broker |
Comment thread
rain-marvin[bot] marked this conversation as resolved.
| `liq_usdc_onchain_available` | | `inventory` | primary chain vault |
| `liq_usdc_onchain_inflight` | | `inventory` | primary chain vault in flight |
| `liq_usdc_offchain_available` | | `inventory` | broker cash after the reserve |
Expand All @@ -162,6 +165,9 @@ second writer. A test scans `src/` for this.
| `liq_usdc_total` | | `inventory` | vault plus broker total plus in flight |
| `liq_usdc_ratio` | | `inventory` | vault over vault plus broker total; `0` when both are 0 |
| `liq_usdc_rebalanceable` | | `inventory` | withdrawable minus the reserve, never below 0; absent until withdrawable is read |
| `liq_usdc_chain_available` | `chain` | `inventory` | each hedged chain vault a snapshot has read |
| `liq_usdc_chain_inflight` | `chain` | `inventory` | as above |
| `liq_usdc_chain_ratio` | `chain` | `inventory` | vault available over itself plus gross broker cash; absent until the gross is read or both are 0 |
| `liq_collector_last_success_ts_seconds` | `collector` | store | Unix time each family was last published |

`symbol` labels drop a leading `wt` or `t` only before an uppercase letter
Expand Down
6 changes: 6 additions & 0 deletions scripts/liq-parity/compare.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,12 @@
# Names only the bot publishes.
BOT_ONLY = {
"liq_collector_last_success_ts_seconds",
"liq_usdc_corridor_target",
"liq_usdc_corridor_deviation",
"liq_equity_chain_available",
"liq_usdc_chain_available",
"liq_usdc_chain_inflight",
"liq_usdc_chain_ratio",
}

# Exporter names that are not ported, because nothing reads them or the bot
Expand Down
2 changes: 2 additions & 0 deletions scripts/liq-parity/testdata/bot.prom
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ liq_settings_cash_reserved 1000
liq_asset_rebalancing{symbol="AAPL"} 1
# TYPE liq_equity_total gauge
liq_equity_total{symbol="AAPL"} 5
# TYPE liq_usdc_chain_available gauge
liq_usdc_chain_available{chain="robinhood"} 10
# TYPE liq_collector_last_success_ts_seconds gauge
liq_collector_last_success_ts_seconds{collector="settings"} 1700000100
# TYPE hedge_trades_total counter
Expand Down
Loading
Loading