diff --git a/README.md b/README.md index 0a4036c..bb58ba2 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,68 @@ -# Buffer +
-> **In 20 seconds.** Buffer shows what a market move would do to your perpetual positions: paste an address or connect a wallet, read Velocity and Pacifica accounts, and explore a shared −20% to +20% price move with the arithmetic in the open. Try it: [bufferonsolana.vercel.app/app](https://bufferonsolana.vercel.app/app). Built by Matt ([RVAClassic](https://x.com/operatoruplift), Operator Uplift) for the Solana Foundation **Perps & Prediction Markets** sprint, September 2026. Working today: live account reads across 76 Pacifica and 4 Velocity markets, Jupiter Perps inventory, installable PWA, Seeker Android shell, one-tap address fill through Mobile Wallet Adapter. Read-only by design: Buffer explains exposure and never trades or signs; its liquidation estimate is a separately versioned model shown beside the provider’s maintenance context, not a forecast from the protocol’s liquidation engine; legacy Drift stays a clearly labeled historical read because that deployment is paused. Everything below is verification detail, scoped to what the code does and what has actually been observed. +Buffer. Perpetuals, risk, Solana. Every position. Every price move. Read-only scenarios for Solana perpetual positions on Velocity, Pacifica and Jupiter Perps, with the arithmetic in the open. -20% to +20% price moves, 76 Pacifica markets, nothing is signed, JSON reports. bufferonsolana.vercel.app -**Understand what a market move would do to your perpetual positions.** Buffer reads Velocity and Pacifica accounts for precise price scenarios, adds Jupiter Perps position inventory with its modeling scope stated in the open, and keeps legacy Drift as a clearly labeled historical read. Explore the responsive web app, inspect coverage, and keep dated reports without connecting a wallet. +

-**Last updated:** September 16, 2026. +Open the explorer   +Watch the films   +Read the risk model -[Website](https://bufferonsolana.vercel.app) · [Open the app](https://bufferonsolana.vercel.app/app) · [Watch the demos](https://bufferonsolana.vercel.app/demo) · [Public source](https://github.com/operatoruplift/buffer) +

-Paste a public Solana wallet address, select an account, and explore a shared −20% to +20% price move. Pacifica adds **76 perpetual markets**, spanning crypto, equities, commodities, FX, and indexes. Velocity supports its four current SOL, BTC, ETH, and HYPE markets. The searchable market list shows coverage for each provider. Twelve deterministic fixture scenarios and a new editable four-market portfolio work immediately; **Explore a live account** loads a public example for the selected provider without a wallet connection. Market counts describe provider listings, not unique assets across exchanges. +CI status +Site status +Reads Velocity, Pacifica and Jupiter Perps +Solana mainnet +Trading: none +Node 24 +License: MIT -## What is included +

Explore the price effect on your Solana perpetual positions, with the source, assumptions and coverage in view.

-- A responsive website and app workspace with desktop sidebar and mobile bottom navigation for Overview, Positions, What-if, and Alerts. Moving between sections preserves portfolio edits and the selected account. -- A sample-only portfolio builder. The default 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. **Add perps** searches all 76 configured sample identities; each position supports Long or Short, editable quantity and baseline price, and removal. USDC, USDT, and USD are illustrative denominations: changing the label preserves the numbers, performs no FX conversion, and creates no trade or provider read. Refreshing a sample preserves custom positions and resets only the price move. -- Live Velocity account discovery through the official `@velocity-exchange/sdk` **0.23.1**, explicit subaccount selection, position contributions, collateral/debt/order inventory, freshness checks, and a Method dialog. -- Public Pacifica account and position reads through its fixed official REST API. All 76 configured perpetual identities are checked against current market metadata, with API price timestamps and USD scenario totals. No API key or RPC configuration is required for Pacifica. See [Pacifica integration](docs/PACIFICA.md). -- A live **inventory-only Jupiter Perps reader** for canonical SOL, ETH, and BTC position identities. It shows direction, USD position size, entry price, recorded collateral, reserved collateral-token amounts, and source accounts/read slots. Jupiter stays out of the linear scenario total by design: an honest Jupiter scenario needs the current oracle contract, collateral dependencies, and the maximum-profit cap modeled together, so Buffer reports the inventory it can verify rather than approximating a capped payoff. See [Jupiter verification](docs/JUPITER-VERIFICATION.md). -- An explicit legacy Drift provider for historical reads. That deployment is paused and its balances do not migrate to Velocity, so Buffer presents it as history and links to the official migration reference instead of silently mixing deployments. -- Precise JSON downloads with price-model identity, version, and formula; device-local saved reports with no account; and optional Supabase sign-in to save, download, and delete private historical reports. Older reports remain readable without rewriting their original contents. -- A PWA for supported mobile and desktop browsers, with original app icons and a clearly labeled offline sample. -- A shared cobalt Brand component across the landing header, app, demo, auth screen, and footer, plus continuous hero and install motion with small icon pause controls and `prefers-reduced-motion` support. -- Refreshed 1080p product, pitch, and technical films with current workspace recordings, conversational narration, synchronized captions, transcripts, and downloads. [Video provenance](docs/VIDEO.md) identifies captured mainnet observations, illustrative inputs, and the synthetic voice. +Choose  →  Read  →  Move prices  →  Explain  →  Report -The public site is hosted on Vercel. Fresh local reads verified modeled Velocity and Pacifica positions and Jupiter inventory; these are point-in-time observations, not fixed example balances. Every live load refetches its source and exposes the relevant API timestamps or account/read slots. [Provider coverage](docs/PROVIDER-COVERAGE.md) and [current verification](docs/REDESIGN-VERIFICATION.md) separate implemented behavior, live evidence, and remaining external requirements. **Cloud sign-in is open to confirmed accounts, and public self-service signup and password recovery come with a deployment that configures production SMTP, exact Auth redirect URLs, and a server-side password policy, then sets `NEXT_PUBLIC_AUTH_EMAIL_READY=true`.** The public explorer and device-local reports need no sign-in at all. See [deployment status](docs/DEPLOYMENT.md) for cloud configuration. +
-The landing and app offer **Explore live risk**: a validated public Velocity account link, fresh reads, automatic selection for one discovered subaccount and deliberate selection for multiple. Current maintenance context sits beside the independent price scenario. [Alert behavior and setup](docs/ALERTS.md) distinguish rehearsal, live checks, Discord acceptance and a matching message receipt. +How it works  ·  +Providers  ·  +Status  ·  +Run it locally  ·  +Docs -## Run locally +
-```sh -nvm install -nvm use -npm ci -cp .env.example .env.local -npm run dev -- --port 3001 -``` +
-Open `http://127.0.0.1:3001`; the explorer is at `/app`. Local Node is pinned to **24.16.0** in `.nvmrc`; `package.json` accepts Node **24.x**. Vercel selects a supported 24.x patch; the verified deployment used **24.19.0**. + + + Four screens of the Buffer explorer with its sample portfolio. 01, start with a portfolio: the four-market sample needs no account or RPC, with SOL, BTC, ETH and XRP at fixed reference prices and every value editable. 02, move every price at once: pick a shared move from -20% to +20%; at -10% the sample's four contributions add up to +1,000 USDC. 03, read the method: one panel gives the formula, what stays fixed and what is excluded, with the source identity and freshness. 04, keep a dated report: save the scenario on this device with no sign-up, or download precise JSON; saved reports never refresh. + -| Environment variable | Purpose | -| --- | --- | -| `SOLANA_RPC_URL` | Server-only Solana mainnet RPC for Velocity, Jupiter inventory, and legacy Drift. Samples and Pacifica work without it. | -| `SOLANA_DEVNET_RPC_URL` | Optional server-only devnet RPC for Velocity devnet reads. Without it, devnet reads use Solana's public `https://api.devnet.solana.com`. | -| `NEXT_PUBLIC_SUPABASE_URL` | Optional dedicated Supabase project URL. | -| `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` | Optional public Supabase key; never a service-role key. | -| `NEXT_PUBLIC_AUTH_EMAIL_READY` | Set `true` on a deployment whose email confirmation and recovery flows are configured and checked end to end. The `false` default keeps the app to sign-in plus the no-account paths. | -| `BUFFER_TEST_AUTHORITY` | Optional public authority for manual verification; not automatically loaded by the app. | +

Captured from a local production build on 30 October 2026, using the app's built-in sample portfolio and fixed reference snapshot. No live account was read.

-The RPC must support `getGenesisHash`, filtered `getProgramAccounts`, `getAccountInfo`, `getMultipleAccounts`, and `getSlot`. Do not expose its URL through a `NEXT_PUBLIC_` variable. Public Supabase settings are embedded at build time, so rebuild after changing them. No wallet private key, application AI key, or service-role key is needed. Setup-only credentials shown in `.env.example` are not read by the application. +**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. -## Use Buffer +Built by Matt ([RVAClassic](https://x.com/rvaclassic), [Operator Uplift](https://operatoruplift.com)) for the Solana Foundation **Perps & Prediction Markets** sprint, September 2026. -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** / enter a public wallet address, and select the discovered account. Jupiter is explicitly inventory-only; legacy Drift is labeled as the paused historical deployment it is. With Velocity selected, the **Network** switch reads Velocity's devnet deployment instead (`&network=devnet` in links); **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, use **Add perps** to search all 76 configured sample identities and edit direction, quantity, and baseline price. Accounts are never combined. -2. Inspect the frozen baseline, positions, and inventory. Any metric Buffer cannot source from the provider is labeled **Unavailable** with the reason in plain words, so a missing oracle price or an isolated position stays visible instead of being filled in with a guess. -3. For modeled samples, Velocity, and Pacifica, move the slider, choose a preset, or use arrow keys in 1% steps. **Reset** returns to zero. A successful live **Refresh** reloads the snapshot and resets the shock; sample refresh preserves edited positions and resets only the shock. 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. With a confirmed cloud account, the same screen also saves, downloads, and deletes private cloud copies. Saved copies are historical records and never refresh with the market. +
-Public exploration does not upload a report. Device storage occurs only when a visitor selects **Save current scenario**; cloud storage occurs only when a signed-in user selects it. Supabase row-level security limits cloud records to their owner; report downloads and deterministic samples remain available without an account. +## How it works -## Arithmetic and boundaries + + + You, Buffer and the providers. You choose: a sample portfolio or any public wallet address; Use my wallet only fills in the address, and nothing is ever signed. Buffer models: price P&L equals size times oracle price times move, decimal strings with rounding only for display, and live snapshots that expire within 120 seconds. Providers are read: Velocity accounts through its official SDK, Pacifica's public API with 76 markets, and Jupiter Perps as inventory only. Every result comes with its method, coverage and a JSON report. + -For signed base quantity `q`, frozen external oracle price `p`, and shock fraction `s`: + + + + + + +
Simple math, carefully scoped
Incremental price P&L is signed quantity × frozen oracle price × move. Sizes stay fixed, and collateral-price changes, future fills, funding, fees, borrowing interest and liquidation effects stay outside the model.
Unavailable, never guessed
Any metric Buffer cannot source from the provider is labeled Unavailable with the reason, so a missing oracle price or an isolated position stays visible instead of being filled in. A failed refresh keeps the old snapshot on screen, labeled stale, and stops calculating on it.
Useful without an account
Samples, public reads and device-saved reports need no sign-in or wallet. Connecting a wallet only fills in its public address; Buffer carries no transaction or trading path.
+ +For signed base quantity `q`, frozen external oracle price `p` and shock fraction `s`: ```text Incremental price P&L = q × p × s @@ -70,15 +70,205 @@ Hypothetical price = p × (1 + s) Position notional = abs(q × p) ``` -The default editable portfolio starts with 100 SOL long at 150, −0.5 BTC 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 still demonstrates the smaller two-position arithmetic: −1,500 USDC plus +5,000 USDC equals **+3,500 USDC**. USDC, USDT, and USD in the sample builder are illustrative labels only; changing denomination preserves numeric inputs and performs no FX conversion. Live Velocity positions remain 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 do not create invented USDC live pairs. Zero shock produces zero. Decimal strings preserve precision; rounding occurs only for presentation. Verified quote currencies retain separate totals. +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. + +
+Arithmetic and boundaries, in full +
+ +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](docs/RISK-CONTEXT.md). + +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. + +
-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 remain visible. Unsupported or nonlinear contracts, LP exposure, unknown flags, inactive markets, and invalid oracle prices receive explicit exclusions. This result is incremental perpetual price P&L, not hypothetical account equity or health. 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 [docs/RISK-CONTEXT.md](docs/RISK-CONTEXT.md). +
+Using the explorer +
-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 are 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; 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. + +
+ +

Next.js 16 · React 19 · TypeScript · Velocity SDK 0.23.1 · @solana/web3.js · decimal.js · Supabase · Wallet Standard and Mobile Wallet Adapter · Vitest · Playwright · PWA · Android Web Shell

+ +
+ +## Providers + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProviderWhat Buffer readsHow it is modeled
Velocity
default
Account discovery, explicit subaccount selection, positions, collateral, debt and orders through the official @velocity-exchange/sdk 0.23.1, across its four SOL, BTC, ETH and HYPE markets, on mainnet or devnet.USDT price scenarios, cross-margin maintenance context, and the per-position liquidation estimate. See live protocol providers.
PacificaPublic accounts and positions through its fixed official REST API, with no API key or RPC. All 76 configured perpetual identities, across crypto, equities, commodities, FX and indexes, are checked against current market metadata.USD price effects from API oracle prices with their timestamps. See Pacifica integration.
Jupiter PerpsCanonical SOL, ETH and BTC position identities: direction, USD size, entry price, recorded collateral, reserved collateral-token amounts, and source accounts and read slots.Inventory only. An honest scenario needs the current oracle contract, collateral dependencies and the maximum-profit cap modeled together, so these rows stay out of totals. See Jupiter verification.
Legacy DriftHistorical reads of the paused deployment, whose balances do not migrate to Velocity.History only, linked to the official migration reference and never mixed with Velocity prices.
+ +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](docs/PROVIDER-COVERAGE.md) separates implemented behavior, live evidence and remaining external requirements. + + + + + + + +
Buffer on a phone, What-if tab for a public Velocity account: perp price P&L change of -928.13 USDT if supported perp prices move -10% together, based on a snapshot at 2026-10-08 07:55:24 UTC, with the shared price move slider and presets from -20% to +20%
A live price scenario on a public Velocity account
Buffer on a phone, Overview tab: the liquidation estimate under model cross-margin-hold-others-v1, observed 2026-10-08 07:55:24 UTC, with BTC-PERP long at 42,218.08 USD, -49.09% from 82,928.58 USD, and ETH-PERP long at 1,539.16 USD, -40.05% from 2,567.41 USD
The liquidation estimate, one position at a time
Buffer on a phone, Positions tab for a Pacifica account with 22 positions at fixed sizes and snapshot oracle prices: PONS-PERP short, SP500-PERP long and XAG-PERP short, each with signed size, oracle price and notional
Pacifica positions, 22 on one public account
+ +

From the repository's dApp Store listing kit in docs/dapp-store, which scripts/generate-dapp-store-assets.mjs captures from the live site. The Velocity screens show observations dated 8 October 2026; public account contents change.

+ +
+ +## Status + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LiveThe website and explorer at bufferonsolana.vercel.app: samples, public Velocity and Pacifica reads, Jupiter inventory, device reports, the films, the brand kit and the installable PWA. On 30 September 2026, fresh public provider probes returned two Velocity positions in USDT and 22 Pacifica positions in USD.Integration status
Dry runHosted monitoring of maintenance headroom and of the liquidation distance of one position per rule. A read-only production check on 1 October 2026 found 30 successful cron runs and 30 completed protected worker runs in the preceding 30 minutes, all in dry_run mode. Discord and signed-webhook delivery are implemented, but outbound delivery is not yet verified and no recipient receipt is claimed.Alerts runbook
GatedPublic self-service signup and password recovery. Cloud sign-in is open to confirmed accounts; signup and recovery come with a deployment that configures production SMTP, exact Auth redirect URLs and a server-side password policy, then sets NEXT_PUBLIC_AUTH_EMAIL_READY=true. Production keeps it false.Deployment
ValidatingThe Seeker Android Web Shell (com.operatoruplift.buffer, wrapping /app) with one-tap address fill through Mobile Wallet Adapter, plus the dApp Store listing kit. Web checks do not establish a signed APK release or device compatibility; the on-device steps still need a phone.Seeker and PWA
HackathonBuilt for the Solana Foundation Perps & Prediction Markets sprint. The official event page, checked 11 September 2026, listed 18 to 25 September 2026. The organizers are the authority on eligibility; the submission draft is marked not submitted, and this README claims no submission or acceptance.Submission draft
+ +
+ +## Run it locally + + + + + + + +
Prerequisites
Node 24: .nvmrc pins 24.16.0 and package.json accepts 24.x (the verified deployment used 24.19.0). npm 11, as in CI. No RPC or account is needed for the samples or Pacifica.
Read first
Risk context and model limits, and deployment and cloud configuration before switching on accounts or monitoring.
What the checks prove
Most live UI cases mock API responses so the suite stays deterministic. Live evidence is recorded separately in provider coverage and the integration status.
+ +### 1. Run the app + +```bash +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 +``` -The latest recorded local verification returned eligible Velocity and Pacifica positions and a Jupiter inventory row. Jupiter validates canonical position PDAs, ownership, pool membership, and collateral custody; `lockedAmount` keeps the collateral token's units and is not presented as a verified USD profit cap. Buffer models a Jupiter price scenario once the current oracle contract, collateral dependencies, and maximum-profit cap can be modeled faithfully together, and reports verified inventory in the meantime. The legacy Drift path rejects stale or paused data rather than borrowing Velocity prices. See the [provider matrix](docs/PROVIDER-COVERAGE.md) and [Jupiter evidence](docs/JUPITER-VERIFICATION.md); older Velocity observations remain documented in [PROVIDER.md](docs/PROVIDER.md). +### 2. Before a pull request, run what [CI](.github/workflows/ci.yml) runs + +```bash +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 +``` -## Architecture +CI also verifies the migrations, owner isolation, account deletion and rate limits against a local PGlite database, with no external writes: + +```bash +npm install --prefix /tmp/buffer-pglite --no-package-lock @electric-sql/pglite@0.5.8 +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](docs/DISCORD-ALERTS.md) and [signed webhook alerts](docs/WEBHOOK-ALERTS.md). | +| `SUPABASE_ACCESS_TOKEN`, `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`, `SMTP_SENDER_EMAIL` | Setup-only credentials shown in `.env.example`; the application never reads them. | + +No wallet private key, application AI key or service-role key is needed by the application. + +
+Deploy +
+ +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](docs/DEPLOYMENT.md) for cloud configuration and email setup, [database verification](docs/DATABASE-VERIFICATION.md) for ownership checks, and [PWA documentation](docs/PWA.md) for the per-browser install paths. Recorded activation evidence is in the [integration status](docs/BUFFER-INTEGRATION-STATUS.md). + +
+ +
+Limits, freshness and safety +
+ +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](docs/WEBHOOK-ALERTS.md) 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. + +
+ +
+Architecture and source map +
```text Website / demo gallery Optional email/password sign-in @@ -101,53 +291,54 @@ 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 query validation | `src/server/providers.ts`, `src/server/boundary.ts` | -| Velocity acquisition and cleanup | `src/server/velocity.ts` | -| Velocity coverage and normalization | `src/server/velocity-normalize.ts` | +| 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` | +| 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` | -| Request validation and limits | `src/server/boundary.ts` | -| Types, scenario math, fixtures, editable sample portfolio, reports | `src/lib/`, especially `sample-builder.ts`, `report.ts`, and `device-reports.ts` | -| Private report schema and policies | `supabase/migrations/` | +| 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/` | -The application uses Next.js **16.3.4**, React **19.3.0**, TypeScript **5.9.3**, Velocity SDK **0.23.1**, Velocity's 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**. Direct versions and the lockfile are pinned. Captured public State, perp, spot, and oracle buffers guard both the current Velocity decoder and the legacy Drift compatibility path. +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. -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. The process cap is 60 reads/minute and four concurrent reads; a scaled service needs a shared ingress limit. Provider errors are sanitized and never silently replaced by samples. A failed refresh keeps the previous snapshot on screen, labels it stale, and stops calculating on it until a fresh read succeeds. Generation checks prevent 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; uncertain cloud writes require reloading the library before retry. +
-Read-only by design: Buffer never signs, never takes custody, and carries no transaction or trading path; connecting a wallet only fills in its public address. Hosted monitoring of maintenance headroom, and of the estimated liquidation distance of one position per rule, 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](docs/WEBHOOK-ALERTS.md) 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. Installation uses each browser's own PWA install path on supported phones, tablets, and desktops, plus the Android Web Shell in `android/`, which builds a signed APK for Seeker and the dApp Store with your own release keystore. +
+Brand, films and design +
-## Verify and deploy - -```sh -npm run typecheck -npm run lint -npm test -npm run build -npm run test:e2e -``` +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. -Install Chromium with `npx playwright install chromium` if necessary. Playwright normally launches or reuses port 3001. 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. Most live UI state cases deliberately mock API responses so the suite stays deterministic; live RPC evidence is recorded separately in [provider coverage](docs/PROVIDER-COVERAGE.md). +The [brand collection](https://bufferonsolana.vercel.app/brand-kit) 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](design/brand-kit/README.md) are included; the site needs no runtime image service. -Vercel uses the explicit Next.js framework setting in `vercel.json`, Node route execution, and 30-second RPC function limits. 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. See the [integration status](docs/BUFFER-INTEGRATION-STATUS.md) for the recorded activation evidence. The server RPC must be a Solana mainnet endpoint; use a dedicated endpoint for sustained production capacity. Follow [deployment](docs/DEPLOYMENT.md) for cloud configuration and email setup, [database verification](docs/DATABASE-VERIFICATION.md) for ownership checks, and [PWA documentation](docs/PWA.md) for the per-browser install paths. +The [demo page](https://bufferonsolana.vercel.app/demo) opens with the [launch film](docs/LAUNCH-FILM.md), followed by the product, pitch and technical films with conversational narration, captions, transcripts and 1080p downloads. [Video provenance](docs/VIDEO.md) identifies captured mainnet observations, illustrative inputs and the synthetic voice. -## Descriptions, design, and videos +
-- [Short and full Markdown descriptions](docs/DESCRIPTION.md) -- [Design references and MotionSites recommendations](docs/DESIGN.md) -- [Video files, transcripts, and Higgsfield provenance](docs/VIDEO.md) -- [Submission draft and sample demonstration](docs/SUBMISSION.md) +
-Buffer's ribbon B monogram, wordmark, favicon, transparent PNG, and monochrome variants live in `public/brand/`; install icons are in `public/icons/`. The primary browser icon is the blue install tile at `/icons/icon.svg?v=tile4`; `public/favicon.ico` retains the unchanged 192×192 PNG fallback. The shared `Brand` component uses the cobalt mark and Helvetica/Arial at weight 550 across the landing header, app, demo, auth screen, and footer. Verified token marks live in `public/tokens/`, including transparent Solana and USDT assets, and the shared `TokenIcon` component reuses those local originals for market rows and the sample builder. The UI and media distinguish product identity from descriptive protocol names and sample data. +## Documentation -The [brand collection](https://bufferonsolana.vercel.app/brand-kit) includes 15 individually composed profile images, phone/4K desktop wallpapers, X/LinkedIn/YouTube headers, social posts, stories, and clean backgrounds. Daylight glass and midnight cobalt artwork share the exact existing ribbon mark. Full-image previews, category filters, mobile original-image links, and a complete ZIP make the assets usable directly from a phone. [Art direction, source prompts, and the local export pipeline](design/brand-kit/README.md) are included; the site needs no runtime image service. + + + + + + + + + + + +
Understand it
Short and full descriptions
Risk context and model limits
Provider coverage
Live protocol providers, Pacifica and Jupiter
Operate it
Deployment and cloud configuration
Database verification
Threshold monitoring runbook
Discord and signed webhook alerts
Check it
Integration status
Current verification
Reliability audit
Production release, 20 September 2026
Show it
Films, transcripts and provenance
Launch film
Design references
Brand kit source
Ship it
Seeker, Android and PWA
Install paths per browser
dApp Store listing kit
Submit it
Submission draft and sample demonstration
-The [official event page](https://hackathons.solana.com/hackathons/perps-and-prediction-markets), checked September 11, lists September 18–25, 2026. Buffer is built for that sprint; the organizers are the authority on eligibility, and this README claims no submission or acceptance. +
-## Seeker, Android and PWA +

Buffer is MIT licensed (see LICENSE); dependencies, token marks and media keep their own licenses and provenance. Buffer is a read-only tool: as its terms say, it is not trading or investment advice, and its liquidation estimate is a separately versioned model, not a forecast from a protocol's liquidation engine.

-Buffer installs as a PWA and ships an Android WebView shell (`android/`) for the Solana Seeker and dApp Store, with Solana Mobile Wallet Adapter support where the app connects a wallet. Build, test and publishing steps: [docs/seeker-and-pwa.md](docs/seeker-and-pwa.md). +

Built by Matt Sim, founder of Operator Uplift. More builds at github.com/operatoruplift. Want one built for your product? Book a 15-minute call.

diff --git a/docs/readme/banner.png b/docs/readme/banner.png new file mode 100644 index 0000000..57684ca Binary files /dev/null and b/docs/readme/banner.png differ diff --git a/docs/readme/flow-dark.png b/docs/readme/flow-dark.png new file mode 100644 index 0000000..00d4844 Binary files /dev/null and b/docs/readme/flow-dark.png differ diff --git a/docs/readme/flow-light.png b/docs/readme/flow-light.png new file mode 100644 index 0000000..f834a92 Binary files /dev/null and b/docs/readme/flow-light.png differ diff --git a/docs/readme/screens-dark.png b/docs/readme/screens-dark.png new file mode 100644 index 0000000..2502c86 Binary files /dev/null and b/docs/readme/screens-dark.png differ diff --git a/docs/readme/screens-light.png b/docs/readme/screens-light.png new file mode 100644 index 0000000..2b8158d Binary files /dev/null and b/docs/readme/screens-light.png differ diff --git a/package.json b/package.json index 549e3c8..cc307ef 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,12 @@ { "name": "buffer-perps", "version": "1.0.0", + "description": "Read-only scenarios for Solana perpetual positions: Velocity, Pacifica and Jupiter Perps reads with the arithmetic in the open.", + "homepage": "https://bufferonsolana.vercel.app", + "repository": { + "type": "git", + "url": "git+https://github.com/operatoruplift/buffer.git" + }, "private": true, "engines": { "node": "24.x"