# Turn an existing priority-fee response into a bounded cost plan

Local buyer helper, 5 November 2026. No new API, dependency, payment, provider
request or transaction. Not a published SDK or proof of improved transaction
inclusion, real buyer adoption or revenue.

The single `.mjs` helper runs standalone in Node 22.23.4 or newer without package installation.
Copy/download only that file into your integration; no Scry server import or
`node_modules` directory is needed. The repository test suite separately reuses
the existing response decorators to check public-format compatibility.

`examples/priority-fee-plan.mjs` answers a concrete question: **Does the chosen
fee tier fit my priority-fee budget for the compute-unit limit I will actually
request?** It consumes a response you already obtained from Scry's existing
Priority Fees Live product. It neither buys that response nor builds, simulates,
signs or sends a Solana transaction.

## Formula and scope

For legacy and v0 transactions, the priority fee in lamports is
`ceil(micro_lamports_per_compute_unit * requested_compute_unit_limit / 1000000)`.
The requested limit matters, not measured consumption. The helper uses exact
integer arithmetic throughout and formats SOL with nine decimal places. The
caller must explicitly identify `legacy` or `v0`; the v1 transaction format
uses an absolute fee instead and is deliberately not supported here.
See [Solana's fee structure](https://solana.com/docs/core/fees/fee-structure).

Supply the actual planned CU limit, from 1 to 1,400,000. Do not pass measured
consumption if the final transaction requests a different limit. The helper
does not choose defaults, add a safety margin or silently clamp the limit.
The upper bound follows the [official compute budget documentation](https://solana.com/docs/core/fees/compute-budget),
checked 5 November 2026. Those docs recommend simulation to choose a suitable
limit; any simulation or submission is a separate caller-owned action.

This is **only the priority fee**. It excludes the Scry API service price
(currently $0.005 in USDC per request), base/signature fees, rent, account
creation, tips, transaction value and other costs. The lamport budget is not a
total-wallet budget and does not authorize spending. No exchange-rate conversion
or total transaction-cost estimate is made.

## Existing-response integration

```js
import { planPriorityFee } from '../examples/priority-fee-plan.mjs';

// existingResponse came from your separately controlled Scry client.
const plan = planPriorityFee({
  response: existingResponse,
  transactionVersion: 'v0',
  computeUnitLimit: 200000, // must match the final transaction's requested limit
  tier: 'high',
  maxPriorityFeeLamports: '3000', // exact decimal string, not a floating number
  maxAgeSeconds: 20, // explicit caller freshness policy
  now: new Date().toISOString(),
  expectedScope: { preset: 'global' },
});
console.log(plan);
// Do not treat this arithmetic result as permission to sign or submit.
```

At 15,000 micro-lamports per CU and 200,000 requested CU, the calculated
priority fee is 3,000 lamports / `0.000003000` SOL. This is a synthetic numerical
illustration, not a current fee quote.

Named scopes are `global`, `jupiter_swap` and `raydium_amm`. The helper binds
both the reported preset and its known account set. For a custom scope, use
`expectedScope: { preset: 'global', accountKeys: [/* your expected keys */] }`
and obtain the response using that same preset plus those custom keys. Custom
keys override the named preset's default keys, as on the existing endpoint.
The nonempty set must match exactly, ignoring ordering; duplicate, invalid or
more than 20 keys are rejected. A program preset is not evidence that the exact
writable accounts of your final transaction were simulated.

Available explicit tiers: `min`, `low`, `medium`, `high`, `veryHigh`, `unsafeMax`
and `recommended`. The last selects the response's existing
`recommended_micro_lamports`; it does not run a new recommendation. `unsafeMax`
is a provider label, not an endorsement. Missing tiers never fall back to a
different tier. The selected JSON number must be a nonnegative safe integer;
unsafe values are rejected because precision already lost in JSON cannot be
recovered. Multiplication after validation uses BigInt, including amounts larger
than JavaScript's safe-number range. Budget strings are bounded to unsigned u64.

## Results and refusal conditions

- `within_budget`: the selected tier fits the supplied priority-fee-only budget.
  `payment_authorized` and `transaction_authorized` remain false.
- `over_budget`: the exact requested cost is returned unchanged for inspection.
  There is no price clamp, reduced CU limit or automatic cheaper tier.
- `needs_review`: invalid input or unusable evidence. No calculated fee is returned.

The helper rejects unavailable/partial/error responses, unsupported products,
unknown units, missing selected prices, warnings or missing source coverage,
frozen examples, and future/stale/inconsistent timestamps. Source freshness is
based on `source_updated_at` and matching `coverage.last_refreshed_at`, not a new
response-generation time. Timestamps must be unambiguous UTC ISO strings with
`Z`; `now` is explicit. `maxAgeSeconds` accepts whole seconds from 1 to 86,400;
that local input bound is not a recommended acceptable age. Most transaction
builders should choose a far smaller bound for these rapidly changing estimates.

The input is caller-supplied: a nonempty list of source labels does not authenticate it.
This helper cannot prove transport authenticity, the validity of the caller's
clock, correspondence with a final transaction, or current on-chain conditions.
Revalidate those before any separately authorized action. Never strip fixture
markers or rewrite old source timestamps to make a response pass. Public frozen
fixtures are always rejected, even with a historical `now`; there is no bypass
mode that produces a live-looking plan.

## JSON stdin CLI and offline checks

The CLI reads exactly one JSON document from stdin, at most 256 KiB and within
10 seconds. It reads no filenames, wallets, environment secrets, network or DB.

```sh
node examples/priority-fee-plan.mjs < caller-owned-plan-input.json
node --test test/priority-fee-plan.test.js
```

Exit 0 means arithmetic `within_budget`, 2 means `over_budget`/`needs_review`,
and 1 means malformed CLI/JSON input. These exit codes never authorize spending.
Tests use in-memory synthetic responses and subprocess stdin, covering
rounding, safe-number boundaries, budgets, scope, freshness and refusal paths.
One test copies the standalone file into an isolated temporary folder, executes
it without package installation, and removes only that test-owned copy.
They do not prove a live paid delivery, transaction success or business uplift.
