diff --git a/docs/superpowers/specs/2026-04-26-token-message-rich-design.md b/docs/superpowers/specs/2026-04-26-token-message-rich-design.md new file mode 100644 index 0000000..9ffa610 --- /dev/null +++ b/docs/superpowers/specs/2026-04-26-token-message-rich-design.md @@ -0,0 +1,130 @@ +# Token message rich design + +## Context + +Current token message flow returns early for Alpha tokens, so users cannot see Spot/Future together with Alpha when multiple sources are available. Message content is also rigid and less informative for partial-source cases. + +Goal: redesign Telegram token message so each available price source is shown in one rich message, with stable ordering and conditional rows. + +## Scope + +Applies to token query message rendering in Telegram bot (`OnTokenInfoByToken` flow and price view formatting). + +Out of scope: +- changing market data fetch logic +- changing command routing +- trend arrows / historical diff + +## Requirements + +1. Rich, multi-line Telegram message format. +2. Spot is primary source when present. +3. Show all available sources in a single message: Spot, Future, Alpha. +4. Hide rows for missing data. +5. Show Basis only when both Spot and Future exist. +6. Show Alpha 24h when Alpha data exists. +7. No trend arrows. +8. Preserve current behavior of no reply when no Spot/Future/Alpha data exists. + +## Message format + +Fixed row order (hide missing rows): + +1. `🪙 TOKEN` +2. `💵 Spot: ...` (primary if exists) +3. `📈 Future: ...` +4. `🅰️ Alpha: ...` +5. `🧭 Basis: Future-Spot` (only if Spot+Future) +6. `💸 Funding: ... in ...` (if Future exists) +7. `🏦 Margin: ... APR` (if margin exists) +8. `📊 Alpha 24h: ...` (if Alpha change exists) + +## Fallback rules + +- **All three available**: render all rows above (except any missing optional fields). +- **Spot + Future**: render Spot, Future, Basis, Funding, Margin. +- **Alpha only**: render Alpha and Alpha 24h. +- **Future only**: render Future, Funding, Margin. +- **Spot only**: render Spot, Margin. +- **No Spot/Future/Alpha**: no reply. + +## Data flow behavior + +1. Resolve token to candidate futures symbol(s) using existing resolver. +2. Collect available values from Spot/Future/Alpha/margin sources. +3. Build one unified message model. +4. Render rows in fixed order; each row is conditional on availability. +5. Send single Telegram message. + +Important behavioral change: remove alpha-first early-return behavior; Alpha becomes a peer data source in unified rendering. + +## Formatting notes + +- Reuse existing numeric formatter (`RenderPrice`) for price values. +- Keep current funding icon and countdown style. +- Basis format: + - absolute delta: `Future - Spot` + - percent delta: `(Future-Spot)/Spot*100` + - sign preserved (`+`/`-`) + +## Example outputs + +### A) Spot + Future + Alpha + +```text +🪙 ETH +💵 Spot: $3,245 +📈 Future: $3,251 +🅰️ Alpha: $3,248 +🧭 Basis: +$6 (+0.18%) +💸 Funding: +0.0123% 🟢 in 05m +🏦 Margin: 7.665% APR +📊 Alpha 24h: 🔴 -3.21% +``` + +### B) Spot + Future + +```text +🪙 SOL +💵 Spot: $182.4 +📈 Future: $183.0 +🧭 Basis: +$0.6 (+0.33%) +💸 Funding: -0.0041% 🔴 in 42m +🏦 Margin: 5.110% APR +``` + +### C) Alpha only + +```text +🪙 ABC +🅰️ Alpha: $0.1234 +📊 Alpha 24h: 🟢 +12.40% +``` + +### D) Future only + +```text +🪙 TOKEN +📈 Future: $1,234 +💸 Funding: +0.0081% 🟢 in 17m +🏦 Margin: 6.200% APR +``` + +### E) Spot only + +```text +🪙 TOKEN +💵 Spot: $1,228 +🏦 Margin: 6.200% APR +``` + +## Verification checklist + +- Token with all 3 sources -> all expected rows appear, ordered correctly. +- Token with Spot+Future but no Alpha -> no Alpha rows. +- Token with Alpha only -> no Spot/Future/Basis/Funding rows. +- Token with Future only -> no Spot/Basis/Alpha rows. +- Token with Spot only -> no Future/Basis/Funding/Alpha rows. +- Token with no data -> no reply. +- Basis not shown unless both Spot and Future exist. +- No trend arrows anywhere.