Welcome to GAUGE

GAUGE is a read-only cockpit + Telegram alerts for Topaz DEX, the ve(3,3) AMM on BNB Chain. It does one thing well: gives you the visual + push-notification surface that the official Topaz Agent (which is conversational by design) structurally can't.

Everything in GAUGE is observe-only. We never request a wallet signature. We never hold funds. We never broadcast a transaction. If an action requires moving tokens or voting on-chain, GAUGE points you to the Topaz Agent — that's its lane.

How GAUGE fits with the rest of Topaz

There are three best-of-breed surfaces for a Topaz user, and each one is best at something different:

Every “ask the Agent” button on GAUGE deep-links to agents.topazdex.com. We send the Agent traffic; we don't steal it. The relationship is complementary, not competitive.

Quick start

You can use GAUGE three ways. Most users do all three within a week.

1. Just browse it. gaugedex.app opens to a live cockpit with TVL, 24h volume, $/vote leaderboard, and a 30-day protocol chart strip. No wallet needed.
2. Connect a wallet or view any address. /wallet renders your veTOPAZ locks, CL positions (free + staked), v2 LP positions, and claimable rewards. Drops to /wallet?address=0x… for any public address — handy for tracking known whales or friends' treasuries.
3. Start the Telegram bot. DM @GaugeAlerts_bot with /start, then /watch 0xYOUR_ADDRESS. You're now subscribed to drift warnings, out-of-range transitions, $5+ claimables, lock-expiry pings, and vote-deadline reminders.
4. Tune your alert preferences. Send /settings to the bot. Configure your min claim-alert threshold, enable quiet hours (22:00–07:00 UTC), or switch to one daily digest DM with /digest on.

Concepts — the language GAUGE speaks

These terms are scattered through Topaz docs and ve(3,3) prior art (Solidly, Aerodrome, Velodrome). If you've been around ve(3,3) you know them; if you haven't, the next five paragraphs are the whole vocabulary.

ve(3,3)

Topaz uses the vote-escrow (ve) model: you lock the protocol token ($TOPAZ) for up to 4 years in exchange for veTOPAZ, an NFT representing your locked stake and voting power. The longer you lock, the more voting power you get. You use that voting power each week to direct $TOPAZ emissions to specific liquidity pools (“gauges”). In exchange, the protocol gives you 100% of the swap fees from the pools you voted for, plus any external bribes deposited by people who want you to vote a specific way.

Epoch

One voting cycle. On Topaz, an epoch is exactly one week, flipping every Thursday at 00:00 UTC. Bribes accumulate during the epoch; votes are cast during the epoch; fees + bribes are claimable after the epoch flips. The header of GAUGE always shows a live countdown to the next flip.

Gauge

A contract that distributes $TOPAZ emissions to liquidity providers of a specific pool. One pool, one gauge. When you “vote on a gauge,” you're telling the protocol which pool deserves emissions this epoch.

Bribe

An external incentive deposited on a gauge to attract veTOPAZ votes. If a project wants more liquidity in its pool, it deposits bribes (usually its own token or a stablecoin) on the pool's gauge. Whoever votes for that gauge claims a pro-rata share of those bribes after the epoch closes.

$/vote (dollar-per-vote)

The single most important number on the bribe market — and the metric GAUGE puts amber-italic on the homepage and headline of the vote optimizer. It's a gauge's total reward pool (fees + bribes posted so far) divided by its current vote weight. Higher $/vote = better return per veTOPAZ if you vote there.

But — and this is the whole point of the optimizer — that number doesn't account for the fact that your own vote dilutes the pool. See The vote optimizer below for the math.

Out of range (OOR), and drift

Topaz v3 uses concentrated liquidity (CL): when you provide liquidity, you choose a price range. While the pool's spot price is inside your range, your LP earns fees. When the price moves outside, you're out of range — your LP stops earning until you rebalance or the price returns.

Drift is GAUGE's term for “you're still in range, but close to the edge.” The bot DMs you a drift warning when any watched position has less than 2% cushion to either edge, so you have a chance to rebalance before you stop earning. Default cushion is 2%; you can tune it via the OOR_RISK_WARN_PCT env.

Dilution

When you allocate v votes to a gauge that already has V votes from others, your share of that gauge is v / (V + v). Crucially, if v is large relative to V, your own vote dilutes the gauge — pushing the marginal return per vote down. A naïve “all-in on the highest $/vote gauge” strategy ignores this and almost always leaves money on the table. The optimizer accounts for it exactly.

Every page, explained

Six pages, each one designed for one specific decision.

Overview · /

The cockpit. Hero band with TVL + total volume sparklines, a live ticking epoch-flip countdown, six protocol-wide stats, the bribe market table (sorted by $/vote), the top pools by TVL, and a 30-day chart strip of protocol TVL / volume / fees. If you have one page open all week, it's this one.

Positions · /wallet

Your wallet's full Topaz footprint. veTOPAZ locks (with unlock countdowns), CL positions (free + staked, grouped by pool, with human-priced range bounds), v2 LP positions, and a claimables card summing your rebase + voting fees + bribes across every veNFT. Works with the connected wallet OR any public address via ?address=0x….

Epoch · /epoch

The weekly decision desk. Big ticking countdown to the next Thursday flip, four-cell state row (bribes posted, foundation share, active gauges, $TOPAZ price), top $/vote leaderboard (every row links into the pool deep-dive), and CTAs into the vote optimizer + your wallet.

Vote · /vote

The vote optimizer. Enter your veTOPAZ power, set your dilution cap, and GAUGE evaluates four allocation strategies in parallel (risk-controlled, max-income, balanced, all-in), picks the Best Move, and shows you a gauge-by-gauge allocation table. See The vote optimizer for the math.

ROI · /roi

Your claimable-rewards history. Drops a localStorage snapshot each time you visit; over weeks, the chart fills in. Three stacked-bar series: rebase, voting fees, bribes. Per-veNFT breakdown below. First visit is a single point; come back tomorrow and the curve takes shape.

Foundation · /foundation

Smart-money tracker for the Topaz team wallet. Wallet header, veNFT count, lifetime bribes received, this-epoch vote allocation table, and a recent-bribe-deposits stream. Combined with the bot's /follow_foundation command, you get DM'd the moment the team wallet votes or receives a fresh bribe — copy-trade smart money in your pocket.

Pool deep-dive · /pool/[address]

Universal drill-down: the bot's /pool command, every pools-table row, and every $/vote leaderboard entry converges here. Header with pair + type, stats grid (TVL / volume / fees / fee tier / APRs), three 30-day trend charts. Built for the “tap to inspect” gesture.

The vote optimizer — the math, in plain English

Most ve(3,3) UIs show you a sorted $/vote leaderboard and expect you to figure out the rest. The math is more interesting than that, and GAUGE solves it explicitly.

The earnings formula

If you allocate v votes to a gauge with reward pool R (fees + bribes posted so far) and existing vote weight V (from everyone else), your earnings are:

earnings = R × v / (V + v)

Notice v appears in both numerator and denominator. As you add more votes, the numerator rises but the denominator rises too. Your marginal return per extra vote diminishes. The first vote you add earns R / V; the millionth might earn 10× less.

Why naïve “all-in” loses

Suppose two gauges:

• Gauge A: R = $1,000, V = 500,000 votes → $/vote = $0.002
• Gauge B: R = $500, V = 500,000 votes → $/vote = $0.001

You have 500,000 votes. All-in on A: earnings = $1,000 × 500k / 1M = $500. Split 50/50: earnings = $1,000 × 250k / 750k + $500 × 250k / 750k = $333 + $167 = $500. Same in this case — but tweak the numbers and one strategy beats the other. The optimal split equalizes the marginal return across the gauges you're voting for; that's the principle.

Water-filling: the mathematical optimum

Setting up a Lagrangian over all gauges and taking the derivative gives an analytical formula for the optimal allocation in gauge i:

v_i(λ) = max(0, √(R_i × V_i / λ) − V_i)

Where λ is the Lagrange multiplier — physically, the marginal return at the optimum. Σ v_i is strictly decreasing in λ, so the algorithm is a binary search: pick the λ where Σ v_i equals your total voting power.

That's “max-income” in GAUGE's strategy comparison. It's the textbook optimal answer if your only goal is to maximize expected income.

Why you might not want max-income

The math is right; the goal might be wrong. Two reasons:

1. Pool concentration risk. “Max income” can put 50%+ of a gauge's post-vote weight on your single vote. If others reroute their votes next epoch, or if the bribe pool turns out smaller than the snapshot suggested, you're uniquely exposed.
2. Snapshot drift. The reward pool R isn't final until the epoch closes — more bribes can arrive, others' votes shift. A diversified split is more robust to that drift.

The four strategies

How “Best Move” is picked

Best Move = the strategy with the highest expected income that respects your dilution cap. If multiple tie on income, GAUGE prefers the simpler strategy: max-income > balanced > risk-controlled > all-in. This ordering means the “Why this won” reasoning is always honest — if the cap wasn't binding, the message won't pretend it was.

The dilution cap, mathematically

Your cap (default 25%, tunable 5–50%) sets the constraint v_i / (V_i + v_i) ≤ cap, which rearranges to:

v_i ≤ V_i × cap / (1 − cap)

The risk-controlled strategy runs the unconstrained water-fill, clips any gauge over v_i_max, and re-runs on the remaining gauges with the clipped allocation deducted. It converges in O(gauges) iterations (usually 1–3).

Caveats

All figures are a current-snapshot estimate. Both R (bribes posted so far) and V (others' current votes) move before the epoch closes. Treat the projected dollar number as a directional estimate, not a quote.

The Telegram bot

Most of the daily-use value of GAUGE is push notifications. The bot is @GaugeAlerts_bot. DM it /start to begin.

Commands

Alert types

When you /watch an address, you become eligible for these alert categories. Each respects your /quiet hours and /digest mode.

• 📍 Drift warning — a CL position is within 2% of an edge. Fires once per warning event; re-arms when cushion recovers above 5%.
• ⚠ Out of range — a CL position has gone fully OOR and stopped earning. Fires once on the transition; re-arms when it comes back in range.
• 💸 Claimables — your total claimable rewards across veNFTs cross your threshold (default $5). Once per UTC day per wallet.
• ⏳ Lock expiry — veTOPAZ lock unlocks soon (7-day, 3-day, 1-day warnings).
• 🗳 Vote reminder — fires in the last 6 hours of an epoch if you haven't voted yet.
• 🐳 Foundation activity — the team wallet voted on a new gauge or received a new bribe (only when you've /follow_foundation'd).

Privacy & security

GAUGE was designed with the same skepticism toward DeFi front-ends that we'd apply to anyone else's. Three guarantees:

1. Read-only. No eth_sign, no eth_sendTransaction. The connect button is for conveniently auto-filling the “view this wallet” field; it doesn't enable any write actions because there are none.
2. No custody. We never touch your funds. The app reads on-chain state directly from a public BNB Chain RPC; the bot reads the Topaz Data API + the same RPC. There is no smart contract in this project.
3. No transaction broadcasts. When an action needs to go on-chain (a vote, a claim, a stake), GAUGE hands you off to the Topaz Agent or the official Topaz app. Those are the surfaces that build calldata; we don't.

What we store

The bot needs a small amount of persistent state to work:

• Subscriber chat IDs — Telegram's numeric IDs for users who've sent /start. These let us send you DMs.
• Watched addresses — the wallets you've added with /watch. Public on-chain data only.
• Alert preferences — your /settings JSON (min claim threshold, quiet hours flag, digest mode).
• Dedupe keys — tiny flags like “already DM'd about this position being OOR” so you don't get spammed every 15 minutes until the situation changes.

That's the whole list. We don't store seed phrases, private keys, signatures, real names, emails, IP addresses, or any analytics. The backing store is Upstash Redis (REST API, server-side only). Deleting yourself is /unwatch for each wallet, then never DM the bot again.

How alerts are delivered

A cron task runs every 15 minutes. It reads the Topaz Data API + does on-chain reads for each watched wallet, evaluates each alert category, and sends DMs via the Telegram Bot API. Quiet hours and digest mode are enforced at the delivery layer, so a setting change takes effect on the next tick.

Source

The project will move to public source under permissive license once the surface stabilizes. In the meantime, if you're a security-curious user or another builder and want a look, reach out.

FAQ

Does GAUGE compete with the Topaz Agent?

No, intentionally. The Agent is best at strategy + calldata building + conversational reasoning. GAUGE is best at visual scanning + push notifications + persistent dashboards. They're different lanes; every “ask the Agent” button on GAUGE deep-links to agents.topazdex.com.

Does the vote optimizer execute votes for me?

No. It computes the optimal allocation and gives you a pre-formatted instruction string (e.g. “Vote my veTOPAZ this epoch: 62% to $RISE/WBNB, 24% to WBNB/TOPAZ, …”) plus a one-click button to copy it and open the Topaz Agent. The Agent builds and broadcasts the actual vote calldata.

Why doesn't my data load instantly?

The cockpit is a client-rendered shell that fetches from the Topaz Data API on hydration. Mobile networks can take ~1–2 seconds. If a fetch fails outright, you'll see a visible “Couldn't load — retry ↻” affordance, not a perpetual skeleton.

Does this work offline?

The app shell is a PWA — install it from your browser's “Add to home screen” menu and the wordmark + chrome will load even offline. Live data (TVL, positions, claimables) requires a connection because it's read fresh every time.

What happens if I lose access to my Telegram?

Nothing on-chain — GAUGE never had any control over your funds. The bot subscription is tied to your Telegram chat ID. A new account = a new /start + /watch.

Will GAUGE always be free?

Yes for the read-only cockpit + the standard alert set. If we ever add features that justify a charge (higher-frequency push, multi-wallet portfolio rollups, etc.), they'll be clearly marked and the existing surface stays free.

Credits & roadmap

GAUGE is built by a friend of the Topaz founder, on his explicit invitation in the official /3rd party tools Telegram channel. It rides on:

• The Topaz Data API — every market number on this dashboard comes from there.
• The Topaz Agent Skill — installed in the dev environment for chain-aware reasoning during builds.
• Direct on-chain reads via viem for everything per-wallet.

What's coming

• $/vote history per gauge — chart how each gauge's $/vote has trended over the last 8 epochs, so you can spot the consistently bribed pools.
• Multi-wallet portfolio — a /portfolio?addrs=a,b,c view that rolls up multiple addresses (treasury + trading + farmer) into one screen.
• Per-category alert toggles — for users who want claim DMs immediately but vote reminders digested.
• OG image cards — sharing a pool deep-dive link should produce a beautiful Twitter/Telegram preview.
• Public source — open up the repo once the surface area stabilizes.

If you're a Topaz user with a feature request, or a builder who wants to integrate with the bot's alert stream, the door's open — find this project on X or in the Topaz Telegram /3rd party tools channel.