diff --git a/README.md b/README.md index 0a4036c..bb58ba2 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,68 @@ -# Buffer +
-**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.
+
+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. +
+| 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. |
+
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
+ +| Provider | +What Buffer reads | +How 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. | +
| Pacifica | +Public 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 Perps | +Canonical 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 Drift | +Historical 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. | +
![]() A live price scenario on a public Velocity account |
+ ![]() The liquidation estimate, one position at a time |
+ ![]() 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.
| The 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 | +|
Hosted 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 | +|
Public 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 | +|
The 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 | +|
| Built 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 | +
| 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. |
+
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"