Buffer

     

Choose  →  Read  →  Move prices  →  Explain  →  Report

How it works  ·  Providers  ·  Status  ·  Run it locally  ·  Docs

Buffer shows what a market move would do to your perpetual positions on Solana. Paste a public address or connect a wallet to fill one in, read a Velocity or Pacifica account, and explore one shared price move from -20% to +20% with the arithmetic in the open. Jupiter Perps adds a position inventory with its modeling scope stated, and legacy Drift stays a clearly labeled historical read because that deployment is paused. Buffer explains exposure and never trades or signs.

Built by Matt (RVAClassic, Operator Uplift) for the Solana Foundation Perps & Prediction Markets sprint, September 2026.

How it works

For signed base quantity q, frozen external oracle price p and shock fraction s:

Incremental price P&L = q × p × s
Hypothetical price   = p × (1 + s)
Position notional    = abs(q × p)

The default editable portfolio starts with 100 SOL long at 150, 0.5 BTC short at 100,000, 8 ETH long at 2,500 and 2,500 XRP long at 2. At -10%, the contributions are -1,500, +5,000, -2,000 and -500 USDC, for a combined +1,000 USDC. The preserved Long + short fixture keeps the smaller two-position example: -1,500 USDC plus +5,000 USDC equals +3,500 USDC. Zero shock produces zero. This result is incremental perpetual price P&L, not hypothetical account equity or health.

USDC, USDT and USD in the sample builder are illustrative labels only; changing the denomination keeps the numeric inputs and performs no FX conversion. Live Velocity positions stay settled in verified USDT, while the SDK's net-value and funding-inclusive P&L baselines are converted and labeled USD. Pacifica API price effects are labeled USD and create no invented USDC pairs. Decimal strings preserve precision; rounding happens only for presentation. Verified quote currencies keep separate totals.

The scenario holds sizes fixed and excludes collateral-price changes, future fills, funding, fees, borrowing interest and liquidation effects. Spot deposits, debts and order counts stay visible. Unsupported or nonlinear contracts, LP exposure, unknown flags, inactive markets and invalid oracle prices receive explicit exclusions.

A separate estimate (model cross-margin-hold-others-v1, live Velocity reads only) solves, one position at a time, the oracle price at which that position alone would bring maintenance collateral down to the maintenance requirement, holding every other price, funding, fee and open order where the provider observed them. The card lists those assumptions and each exclusion. See current risk context and model limits.

Velocity perps use the SDK's applicable oracle validity helper plus Buffer's 150-slot maximum lag. Spot valuation also checks protocol margin staleness, volatility, sufficient data and a 1% confidence cap. Pacifica uses its API's USD oracle prices with a 120-second price-age limit and explicit API provenance; these are not independently verified Solana oracle reads. USDC margin balances stay distinct from USD scenario totals, with no assumed peg conversion. Live snapshots expire at most 120 seconds after retrieval, or earlier when the source price expires. Reads are not atomic. SDK baseline valuation may use a separately validated MM oracle, and cross-margin health is reported only where it describes the positions, so isolated positions never borrow a cross-margin number.

1. Choose among 12 fixed scenarios or the editable four-market portfolio. For public reads, select Velocity (the default), Pacifica or Jupiter Perps, use Explore a live account or enter a public wallet address, and select the discovered account. With Velocity selected, the Network switch reads Velocity's devnet deployment instead (&network=devnet in links), and Explore a devnet account opens a public devnet subaccount holding SOL, ETH and BTC perps. Devnet balances are test values, and background monitoring stays on mainnet. In samples, Add perps searches all 76 configured sample identities, with editable direction, quantity and baseline price. Accounts are never combined.
2. Inspect the frozen baseline, positions and inventory.
3. For modeled samples, Velocity and Pacifica, move the slider, choose a preset or use the arrow keys in 1% steps. Reset returns to zero. A successful live Refresh reloads the snapshot and resets the move; a sample refresh keeps edited positions and resets only the move. Jupiter inventory and legacy Drift stay inventory and history, so neither produces a modeled price effect.
4. Open Method for assumptions, exclusions, addresses, source, and RPC slots or API price timestamps. Download report saves precise JSON locally, including edited sample positions and prices.
5. Open My reports to save the current report on this device with no sign-up (up to 20). With a confirmed cloud account, the same screen also saves, downloads and deletes private cloud copies (up to 50 reports and 8 MiB per account). Saved copies are historical records and never refresh with the market.

Public exploration does not upload a report. Device storage happens only when a visitor selects Save current scenario, and cloud storage only when a signed-in user selects it. Supabase row-level security limits cloud records to their owner, and a signed-in user can delete their account and its data.

The landing page and the app also offer Explore live risk: a validated public Velocity account link with fresh reads, automatic selection when exactly one subaccount is discovered and a deliberate choice when there are several. Current maintenance context sits beside the independent price scenario.

Providers

Market counts describe provider listings, not unique assets across exchanges. Every live load refetches its source and exposes the relevant API timestamps or account and read slots; recorded live observations are point-in-time, not fixed balances. The provider coverage matrix separates implemented behavior, live evidence and remaining external requirements.

Status

Run it locally

1. Run the app

nvm install && nvm use             # Node 24.16.0 from .nvmrc
npm ci
cp .env.example .env.local         # optional: samples and Pacifica need no configuration
npm run dev -- --port 3001         # http://127.0.0.1:3001, and the explorer is at /app

2. Before a pull request, run what CI runs

npm run lint
npm run typecheck
npm test
npm run build
npx playwright install chromium
npm run test:e2e                   # launches or reuses a server on port 3001

CI also verifies the migrations, owner isolation, account deletion and rate limits against a local PGlite database, with no external writes:

npm install --prefix /tmp/buffer-pglite --no-package-lock @electric-sql/[email protected]
export BUFFER_PGLITE_MODULE=/tmp/buffer-pglite/node_modules/@electric-sql/pglite/dist/index.js
node scripts/verify-alert-schema.mjs
node scripts/verify-hosted-monitoring.mjs
node scripts/verify-monitoring-scheduler.mjs
node scripts/verify-account-deletion.mjs
node scripts/verify-rate-limit.mjs
node scripts/verify-saved-report-quota.mjs

Set PLAYWRIGHT_BASE_URL to exercise an already running deployment. Point BUFFER_AUTH_FIXTURES at a private JSON array of two disposable confirmed accounts (email and password) to include the real Auth suite's desktop and mobile cases; every other case runs without it. Never commit fixture credentials. npm run alert:worker -- --fixture runs the local durable mock worker, which has no external delivery.

3. Configuration

Variable	Purpose
SOLANA_RPC_URL	Server-only Solana mainnet RPC for Velocity, Jupiter inventory and legacy Drift. It must support getGenesisHash, filtered getProgramAccounts, getAccountInfo, getMultipleAccounts and getSlot. Never expose it through a NEXT_PUBLIC_ variable.
SOLANA_DEVNET_RPC_URL	Optional server-only devnet RPC for Velocity devnet reads; without it, Solana's public https://api.devnet.solana.com.
BUFFER_TEST_AUTHORITY	Optional public authority with active Velocity positions, for manual verification; the app does not load it.
NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY	Optional dedicated Supabase project and its public key, never a service-role key. Embedded at build time, so rebuild after changing them.
NEXT_PUBLIC_AUTH_EMAIL_READY	true only on a deployment whose email confirmation and recovery are configured and checked end to end. The false default keeps sign-in plus the no-account paths.
NEXT_PUBLIC_SUPPORT_EMAIL	Optional support address on /privacy and /terms; unset points to this repository's issues.
RATE_LIMIT_SECRET	Optional server-only secret for the distributed read limit (needs the protected consume_rate_limit RPC). Unset or unreachable means per-process limits only.
BUFFER_ALERT_STORE	Path for the local SQLite mock worker; defaults to .local/alerts.sqlite.
BUFFER_ALERT_WORKER_SECRET, CRON_SECRET	Hosted monitoring credentials, separate from browser auth. Store only the SHA-256 of the worker secret in private.buffer_monitor_credentials.
BUFFER_ALERT_SEND_ENABLED, BUFFER_ALERT_NOTIFICATION_MODE	Delivery switches, false and test by default.
BUFFER_DISCORD_DESTINATIONS_JSON, BUFFER_WEBHOOK_DESTINATIONS_JSON	Server-admin destinations with owner allowlists. See Discord alerts and .

No wallet private key, application AI key or service-role key is needed by the application.

Vercel uses the explicit Next.js framework setting in vercel.json and Node route execution. The account and snapshot routes allow 30 seconds, as do most monitoring routes; the monitoring check and worker routes allow 60. The dedicated Supabase project, saved-report migrations and owner-scoped alert tables are deployed; the protected worker and Discord adapter activate through their own scheduler credential and recipient verification. The server RPC must be a Solana mainnet endpoint, and a dedicated endpoint is needed for sustained production capacity. Follow deployment for cloud configuration and email setup, database verification for ownership checks, and PWA documentation for the per-browser install paths. Recorded activation evidence is in the integration status.

RPC requests have an 18-second total abort deadline, an 8 MiB decoded response bound and request-owned loaders without polling timers. Pacifica has its own 18-second, 1 MiB fixed-origin boundary. Reads reject redirects and use no-store. Live reads go through a budget: identical requests within five seconds share one provider call, each client may make 30 reads a minute (counted across instances when the shared store is configured), and each instance allows 240 reads a minute with 8 in flight. Provider errors are sanitized and never silently replaced by samples. Generation checks stop late account, subaccount or previous-user responses from replacing current state. Auth writes and SDK storage commits are bound to the initiating user and session, and uncertain cloud writes require reloading the library before a retry.

Hosted monitoring runs on a protected worker with its own server-only credential and scheduler secret. Discord delivery is available on a deployment that registers an owner-scoped destination, verifies that destination's channel and holds recipient authorization; every send reverifies the destination first, and a Discord notification counts as delivered only once a matching message receipt comes back. Signed webhook destinations POST an HMAC-SHA256-signed JSON payload to a server-configured HTTPS URL and count a 2xx acknowledgement as the receipt. Example alerts are an isolated local rehearsal.

The PWA caches only its explicit public offline assets; API responses, Supabase requests, auth, saved reports and live page data bypass that cache.

Website / demo gallery                    Optional email/password sign-in
            │                                           │
            ▼                                           ▼
/app: public explorer                         Supabase Auth session
   ├─ deterministic samples                           │
   └─ /api/accounts → explicit subaccount              ▼
      /api/snapshot → Velocity (default),      saved_reports + owner RLS
                      Pacifica, legacy Drift  ▲  save / download / delete
                      Jupiter (inventory only)
                      │
              RPC or public API validation
                      ▼                              │
              decimal-string Snapshot               │
                      ▼                              │
              pure scenario calculation → JSON report

PWA service worker → public offline sample and icon allowlist only

Area	Source
Website, explorer, account screen, videos	src/app/{page,app/page,auth/page,demo/page}.tsx
Interactive UI	src/components/Landing.tsx, Dashboard.tsx, SampleBuilder.tsx, AccountPanel.tsx, AuthForm.tsx, Brand.tsx, TokenIcon.tsx
Provider selection and request validation and limits	src/server/providers.ts, src/server/boundary.ts, src/server/live-read-budget.ts
Velocity acquisition, coverage and normalization	src/server/velocity.ts, src/server/velocity-normalize.ts
Pacifica public API acquisition and normalization	src/server/pacifica.ts, src/server/pacifica-normalize.ts
Jupiter inventory decoding, validation and acquisition	src/server/jupiter-decoder.ts, jupiter-normalize.ts, jupiter.ts, jupiter-provider.ts
Legacy Drift compatibility	src/server/drift.ts, src/server/normalize.ts
Types, scenario math, fixtures, editable sample portfolio, reports	src/lib/, especially sample-builder.ts, report.ts and device-reports.ts
Private report, alert and monitoring schema and policies	supabase/migrations/
Installation and offline sample	src/app/manifest.ts, src/components/PwaClient.tsx, public/sw.js, public/offline.html
Seeker Android shell	android/

Direct dependency versions and the lockfile are pinned: Next.js 16.4.3, React 19.3.0, TypeScript 5.9.3, Velocity SDK 0.23.1 with its web3.js 1.99.0 alias, legacy Drift SDK 2.161.0-beta.5, spl-token 0.4.13, decimal.js 10.6.0 and Supabase JS 2.116.0. Captured public State, perp, spot and oracle buffers guard both the current Velocity decoder and the legacy Drift compatibility path.

Buffer's ribbon B monogram, wordmark, favicon, transparent PNG and monochrome variants live in public/brand/, and install icons in public/icons/. The primary browser icon is the blue install tile at /icons/icon.svg?v=tile4; public/favicon.ico keeps the 192×192 PNG fallback. The shared Brand component uses the cobalt mark and Helvetica or Arial at weight 550 across the landing header, app, demo, auth screen and footer. Verified token marks live in public/tokens/, and the shared TokenIcon component reuses those local originals for market rows and the sample builder. The UI and media keep product identity apart from descriptive protocol names and sample data.

The brand collection holds 15 individually composed images: profile images, phone and 4K desktop wallpapers, X, LinkedIn and YouTube headers, social posts, a story and clean backgrounds. Daylight glass and midnight cobalt artwork share the exact ribbon mark. Full-image previews, category filters, mobile original-image links and a complete ZIP make the assets usable from a phone. Art direction, source prompts and the local export pipeline are included; the site needs no runtime image service.

The demo page opens with the launch film, followed by the product, pitch and technical films with conversational narration, captions, transcripts and 1080p downloads. Video provenance identifies captured mainnet observations, illustrative inputs and the synthetic voice.

Documentation