@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/shared/lib/wallet/send-rules.js

@@ -0,0 +1,116 @@
+// The rules of sending SUI or WAL out of the wallet — address shape, exact amounts, what can be
+// sent, and the gas budget a person may set. ⚠ PUBLISHED — copied byte-for-byte into the `nmts`
+// command-line package; keep comments self-contained English.
+//
+// CONTRACT: every function is pure — no I/O, no side effects, no network, no dates. Validators
+//   return a discriminated result carrying a STABLE error CODE (a screen maps codes to sentences);
+//   they never throw on bad input and never format for a locale. Base units are 1e9
+//   (1 SUI = 1e9 MIST, 1 WAL = 1e9 FROST).
+// NON-CUSTODIAL: these helpers only DECIDE amounts and addresses that the person's own wallet then
+//   signs; nothing here holds, routes or moves value.
+/** Base-unit scale for both tokens (1 SUI = 1e9 MIST, 1 WAL = 1e9 FROST). */
+export const TOKEN_DECIMALS = 9;
+/**
+ * SUI kept back so a send or exchange can pay its own gas (0.05 SUI). A ceiling, not the charged
+ * amount — a real fee is a few million MIST; this is generous so a send never strands the wallet
+ * without gas.
+ */
+export const SUI_GAS_RESERVE_MIST = 50000000n;
+/** A full Sui address: `0x` + 64 lowercase hex characters. */
+const SUI_ADDRESS_RE = /^0x[0-9a-f]{64}$/;
+/** Trim and lowercase an address (hex is case-insensitive; lowercase is the shape kept). */
+export function normalizeSuiAddress(input) {
+    return input.trim().toLowerCase();
+}
+/** True when `input`, normalised, is a full 0x + 64-hex Sui address. */
+export function isValidSuiAddress(input) {
+    return SUI_ADDRESS_RE.test(normalizeSuiAddress(input));
+}
+/**
+ * A decimal amount ("0.5", "12", ".25") as base units, EXACTLY — no floating point, so 0.1 never
+ * drifts. Null for anything malformed or finer than the chain keeps (never silently rounded). Does
+ * not judge whether the amount is affordable; that is the validator's job.
+ */
+export function parseTokenAmountToBaseUnits(input, decimals = TOKEN_DECIMALS) {
+    const s = input.trim();
+    if (s === "" || s === "." || !/^\d*\.?\d*$/.test(s))
+        return null;
+    const [intPart = "", fracPart = ""] = s.split(".");
+    if (intPart === "" && fracPart === "")
+        return null;
+    if (fracPart.length > decimals)
+        return null;
+    const frac = fracPart.padEnd(decimals, "0");
+    try {
+        return BigInt(`${intPart === "" ? "0" : intPart}${frac}`);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The most that can be sent, in base units. SUI keeps the gas reserve back; WAL is fully sendable
+ * (a WAL transfer pays its gas in SUI, which the validator checks separately). Never negative.
+ */
+export function maxSendableBaseUnits(params) {
+    const reserve = params.gasReserve ?? SUI_GAS_RESERVE_MIST;
+    if (params.coin === "SUI") {
+        const max = params.suiBalance - reserve;
+        return max > 0n ? max : 0n;
+    }
+    return params.walBalance > 0n ? params.walBalance : 0n;
+}
+/**
+ * Validate a send. The address must be a full Sui address; the amount must be above zero and within
+ * what can be sent; a WAL send also needs the gas reserve in SUI — else `noGasForWal`.
+ */
+export function validateSendForm(params) {
+    const reserve = params.gasReserve ?? SUI_GAS_RESERVE_MIST;
+    const address = normalizeSuiAddress(params.addressInput);
+    if (!isValidSuiAddress(address))
+        return { ok: false, error: "invalidAddress" };
+    const amount = parseTokenAmountToBaseUnits(params.amountInput);
+    if (amount === null || amount <= 0n)
+        return { ok: false, error: "invalidAmount" };
+    if (params.coin === "SUI") {
+        const max = maxSendableBaseUnits({
+            coin: "SUI",
+            suiBalance: params.suiBalance,
+            walBalance: params.walBalance,
+            gasReserve: reserve,
+        });
+        if (max <= 0n || amount > max)
+            return { ok: false, error: "insufficientBalance" };
+    }
+    else {
+        if (params.suiBalance < reserve)
+            return { ok: false, error: "noGasForWal" };
+        if (amount > params.walBalance)
+            return { ok: false, error: "insufficientBalance" };
+    }
+    return { ok: true, amountBaseUnits: amount, address };
+}
+/** The lowest gas budget a person may set: 0.002 SUI. Below it no transaction goes through. */
+export const GAS_BUDGET_MIN_MIST = 2000000n;
+/** The absolute ceiling: 1 SUI. A slipped extra zero stops here. */
+export const GAS_BUDGET_ABS_MAX_MIST = 1000000000n;
+/**
+ * The RECOMMENDED gas budget from a measured (dry-run) fee: twice the measurement, at least
+ * 0.005 SUI, at most 1 SUI.
+ *
+ * Why twice: the measurement is taken against this moment's object versions and reference gas
+ * price, and both move a little between signing and broadcast. A budget below the real cost makes
+ * the transaction FAIL FOR WANT OF GAS, and that gas is gone; the doubling is what buys out that
+ * failure. A budget is a ceiling, not a charge — what is not used stays in the wallet.
+ */
+export function recommendedGasBudgetMist(estimateMist) {
+    const doubled = estimateMist * 2n;
+    const floored = doubled > 5000000n ? doubled : 5000000n;
+    return floored < GAS_BUDGET_ABS_MAX_MIST ? floored : GAS_BUDGET_ABS_MAX_MIST;
+}
+/** Keep a typed gas budget inside the usable range — clamped, not refused. */
+export function clampGasBudgetMist(n) {
+    if (n < GAS_BUDGET_MIN_MIST)
+        return GAS_BUDGET_MIN_MIST;
+    return n > GAS_BUDGET_ABS_MAX_MIST ? GAS_BUDGET_ABS_MAX_MIST : n;
+}

package/dist/shared/lib/wallet/swap-rules.d.ts

@@ -0,0 +1,115 @@
+/** Which way the trade runs. Every screen and every command uses these two words only. */
+export type SwapDirection = "SUI_TO_WAL" | "WAL_TO_SUI";
+/** Where the trade runs, on mainnet. */
+export type SwapVenue = "deepbook" | "bluefin";
+/**
+ * The order the two venues are listed in. NOT a ranking: neither is a default and nobody
+ * recommends one — at some amounts one pays more, at others the other. The order is fixed only so
+ * a person finds the same venue in the same place every time.
+ */
+export declare const SWAP_VENUES: readonly SwapVenue[];
+/** The lowest slippage allowance: 1 bps (0.01%). Zero would refuse every price movement. */
+export declare const SLIPPAGE_BPS_MIN = 1;
+/** The highest: 5,000 bps (50%). Above that it is not protection, it is protection switched off. */
+export declare const SLIPPAGE_BPS_MAX = 5000;
+/**
+ * The default: 50 bps (0.5%). The two real mainnet swaps the treasury made came out 0.2% and 0.6%
+ * from their quotes (treasury ledger rows 2 and 3); this sits between those measurements.
+ */
+export declare const SLIPPAGE_BPS_DEFAULT = 50;
+/** Preset buttons. A free number beside them is mandatory — presets alone are never enough. */
+export declare const SLIPPAGE_PRESETS_BPS: readonly number[];
+/**
+ * A typed slippage as a whole number of bps inside the usable range — clamped, not refused: a
+ * person who types 99999 means "as loose as it goes". Not a number, or infinite, goes to the
+ * DEFAULT rather than the ceiling: a broken input must not read as "protection at its loosest".
+ */
+export declare function clampSlippageBps(n: number): number;
+/** Which band a slippage sits in. The warning on every surface reads this one verdict. */
+export type SlippageBand = "low" | "ok" | "high";
+/**
+ * Too low / fine / too high. Below 10 bps the trade fails on the smallest price movement (gas
+ * spent, nothing bought); above 200 bps a thin order book is handed that much for free. Both
+ * edges (10 and 200) are "ok", so the 10 bps preset never warns about itself.
+ */
+export declare function slippageBand(bps: number): SlippageBand;
+/**
+ * The minimum to accept, from a quote: floor(quote × (10000 − bps) / 10000), never negative. Floor,
+ * because rounding up would demand more than the quote and fail a trade that fills exactly as
+ * quoted. A bps outside 0..10000 is folded to that range here; validation is `clampSlippageBps`.
+ */
+export declare function minOutFromQuote(quoteUnits: bigint, slippageBps: number): bigint;
+/** Which band a gas budget sits in — the same three words as slippage, so one warning part serves. */
+export type FeeBand = "low" | "ok" | "high";
+/**
+ * Too low / fine / too high, judged against a measured fee when there is one: low below 1.2× the
+ * measurement (a budget cut to the measurement often falls short by the time it executes), high
+ * above 10× AND above 0.05 SUI (ten times a tiny fee is still small change). With no measurement,
+ * absolute bounds only: above 0.5 SUI is high, below the floor is low. A missing measurement is
+ * never replaced by a plausible one.
+ */
+export declare function feeBand(budgetMist: bigint, estimateMist: bigint | null): FeeBand;
+/**
+ * How far a quote sits from the market rate, in bps, sign-free (the denominator is the market).
+ * Null when either side is not a finite positive number. Unrounded — where to cut digits is the
+ * surface's decision. This is what stops a thin or manipulated order book taking the money: a quote
+ * on its own makes one order book the truth, and an empty one is exactly when a person loses.
+ */
+export declare function priceDeviationBps(impliedRate: number, marketRate: number): number | null;
+/** Beyond this distance from the market rate a quote is an extreme (3%). */
+export declare const DEVIATION_WARN_BPS = 300;
+/** Output per unit of input, as a number for the market comparison. Null when either side is 0. */
+export declare function impliedRate(outUnits: bigint, amountInUnits: bigint): number | null;
+/**
+ * The market rate in the DIRECTION'S OWN unit — WAL per SUI going one way, SUI per WAL the other —
+ * so the two sides of the ratio are never swapped. Null unless both prices are positive numbers.
+ */
+export declare function marketRate(direction: SwapDirection, suiUsd: number | null | undefined, walUsd: number | null | undefined): number | null;
+/**
+ * The most SUI a swap may take in: balance minus the gas budget the person set, never negative.
+ * Not a fixed reserve — the person chose the budget, so that exact figure is what is kept back.
+ */
+export declare function maxSwappableSuiMist(suiBalanceMist: bigint, gasBudgetMist: bigint): bigint;
+/** One reason a swap is outside the ordinary bands. Each maps to one sentence on each surface. */
+export type SwapExtreme = "lowSlippage" | "highSlippage" | "lowFee" | "highFee" | "deviation";
+/**
+ * Every extreme in one trade, in reading order. Empty means ordinary. A budget of null means the
+ * person set none (the SDK will), so there is no fee band to judge; a deviation of null means no
+ * market price was available, which is reported as unknown by the surface, never as "fine".
+ */
+export declare function swapExtremes(input: {
+    slippageBps: number;
+    budgetMist: bigint | null;
+    estimateMist: bigint | null;
+    deviationBps: number | null;
+}): SwapExtreme[];
+/**
+ * A fee in base units as a rate of the amount put in, in bps with two decimals. Bluefin's quote
+ * reports the fee outright (`fee_amount` + `protocol_fee`); both parts count, or the rate reads
+ * smaller than what is charged. Null when nothing went in.
+ */
+export declare function feeRateBpsOf(feeUnits: bigint, amountInUnits: bigint): number | null;
+/** One DeepBook quote row: what comes out, and what went in but was not used. */
+export interface DeepbookQuoteRow {
+    outUnits: bigint;
+    leftoverInUnits: bigint;
+}
+/**
+ * The three values a DeepBook quote returns are always (base side, quote side, DEEP needed); which
+ * of the first two is "received" and which is "left over" depends on the direction. Base = WAL,
+ * quote = SUI on the WAL_SUI book.
+ */
+export declare function deepbookRowFrom(direction: SwapDirection, base: bigint, quote: bigint): DeepbookQuoteRow;
+/**
+ * DeepBook's EFFECTIVE fee rate, measured — there is no constant to read. The same amount is
+ * quoted in two modes: fee taken from the input coin (the mode used, needs no DEEP) and fee paid in
+ * DEEP; the difference is what the input mode kept. ⛔ Outputs alone must not be subtracted:
+ * DeepBook rounds to its lot size and each mode leaves a different remainder, so output per unit
+ * ACTUALLY SPENT is compared (25 WAL measured 0.40% the naive way and 0.127% this way, matching a
+ * 100 SUI trade where rounding vanishes). Integer arithmetic throughout.
+ *
+ * Null, never 0, when it cannot be measured — including a non-positive result, which means the
+ * method broke down (the two modes walked the book to different depths), not that the fee is 0.
+ * DeepBook always charges; "0%" would be a lie.
+ */
+export declare function measureDeepbookFeeBps(amountInUnits: bigint, inputMode: DeepbookQuoteRow, deepMode: DeepbookQuoteRow | null): number | null;

package/dist/shared/lib/wallet/swap-rules.js

@@ -0,0 +1,199 @@
+// The rules of an in-app swap between SUI and WAL — the slippage a person may set, the minimum a
+// quote turns into, the gas-budget bands, the market cross-check, the venue fee arithmetic and the
+// extremes gate. ⚠ PUBLISHED — copied byte-for-byte into the `nmts` command-line package; keep
+// comments self-contained English.
+//
+// CONTRACT: every function is pure — no I/O, no side effects, no network, no dates. Slippage is in
+//   bps (1 bps = 0.01%) and is a number because a person picks it; amounts are base units
+//   (1e9 = one coin) and are bigint because money is never a float.
+// NON-CUSTODIAL: these helpers only DECIDE the numbers a person's own wallet then signs. NMTS is
+//   not a party to the trade and takes nothing from it: no fee argument, no NMTS address.
+import { GAS_BUDGET_MIN_MIST } from "./send-rules.js";
+/**
+ * The order the two venues are listed in. NOT a ranking: neither is a default and nobody
+ * recommends one — at some amounts one pays more, at others the other. The order is fixed only so
+ * a person finds the same venue in the same place every time.
+ */
+export const SWAP_VENUES = ["deepbook", "bluefin"];
+/** The lowest slippage allowance: 1 bps (0.01%). Zero would refuse every price movement. */
+export const SLIPPAGE_BPS_MIN = 1;
+/** The highest: 5,000 bps (50%). Above that it is not protection, it is protection switched off. */
+export const SLIPPAGE_BPS_MAX = 5000;
+/**
+ * The default: 50 bps (0.5%). The two real mainnet swaps the treasury made came out 0.2% and 0.6%
+ * from their quotes (treasury ledger rows 2 and 3); this sits between those measurements.
+ */
+export const SLIPPAGE_BPS_DEFAULT = 50;
+/** Preset buttons. A free number beside them is mandatory — presets alone are never enough. */
+export const SLIPPAGE_PRESETS_BPS = [10, 50, 100];
+/**
+ * A typed slippage as a whole number of bps inside the usable range — clamped, not refused: a
+ * person who types 99999 means "as loose as it goes". Not a number, or infinite, goes to the
+ * DEFAULT rather than the ceiling: a broken input must not read as "protection at its loosest".
+ */
+export function clampSlippageBps(n) {
+    if (!Number.isFinite(n))
+        return SLIPPAGE_BPS_DEFAULT;
+    const rounded = Math.round(n);
+    return Math.min(SLIPPAGE_BPS_MAX, Math.max(SLIPPAGE_BPS_MIN, rounded));
+}
+/**
+ * Too low / fine / too high. Below 10 bps the trade fails on the smallest price movement (gas
+ * spent, nothing bought); above 200 bps a thin order book is handed that much for free. Both
+ * edges (10 and 200) are "ok", so the 10 bps preset never warns about itself.
+ */
+export function slippageBand(bps) {
+    if (bps < 10)
+        return "low";
+    if (bps > 200)
+        return "high";
+    return "ok";
+}
+const BPS_DENOMINATOR = 10000n;
+/**
+ * The minimum to accept, from a quote: floor(quote × (10000 − bps) / 10000), never negative. Floor,
+ * because rounding up would demand more than the quote and fail a trade that fills exactly as
+ * quoted. A bps outside 0..10000 is folded to that range here; validation is `clampSlippageBps`.
+ */
+export function minOutFromQuote(quoteUnits, slippageBps) {
+    if (quoteUnits <= 0n)
+        return 0n;
+    const rounded = Number.isFinite(slippageBps) ? Math.round(slippageBps) : SLIPPAGE_BPS_DEFAULT;
+    const bounded = BigInt(Math.min(10_000, Math.max(0, rounded)));
+    const out = (quoteUnits * (BPS_DENOMINATOR - bounded)) / BPS_DENOMINATOR;
+    return out > 0n ? out : 0n;
+}
+/**
+ * Too low / fine / too high, judged against a measured fee when there is one: low below 1.2× the
+ * measurement (a budget cut to the measurement often falls short by the time it executes), high
+ * above 10× AND above 0.05 SUI (ten times a tiny fee is still small change). With no measurement,
+ * absolute bounds only: above 0.5 SUI is high, below the floor is low. A missing measurement is
+ * never replaced by a plausible one.
+ */
+export function feeBand(budgetMist, estimateMist) {
+    if (estimateMist === null) {
+        if (budgetMist > 500000000n)
+            return "high";
+        return budgetMist < GAS_BUDGET_MIN_MIST ? "low" : "ok";
+    }
+    if (budgetMist < (estimateMist * 12n) / 10n)
+        return "low";
+    if (budgetMist > estimateMist * 10n && budgetMist > 50000000n)
+        return "high";
+    return "ok";
+}
+/**
+ * How far a quote sits from the market rate, in bps, sign-free (the denominator is the market).
+ * Null when either side is not a finite positive number. Unrounded — where to cut digits is the
+ * surface's decision. This is what stops a thin or manipulated order book taking the money: a quote
+ * on its own makes one order book the truth, and an empty one is exactly when a person loses.
+ */
+export function priceDeviationBps(impliedRate, marketRate) {
+    if (!Number.isFinite(impliedRate) || impliedRate <= 0)
+        return null;
+    if (!Number.isFinite(marketRate) || marketRate <= 0)
+        return null;
+    return (Math.abs(impliedRate - marketRate) / marketRate) * 10_000;
+}
+/** Beyond this distance from the market rate a quote is an extreme (3%). */
+export const DEVIATION_WARN_BPS = 300;
+/** Output per unit of input, as a number for the market comparison. Null when either side is 0. */
+export function impliedRate(outUnits, amountInUnits) {
+    if (amountInUnits <= 0n || outUnits <= 0n)
+        return null;
+    const r = Number(outUnits) / Number(amountInUnits);
+    return Number.isFinite(r) && r > 0 ? r : null;
+}
+/**
+ * The market rate in the DIRECTION'S OWN unit — WAL per SUI going one way, SUI per WAL the other —
+ * so the two sides of the ratio are never swapped. Null unless both prices are positive numbers.
+ */
+export function marketRate(direction, suiUsd, walUsd) {
+    if (suiUsd == null || walUsd == null || suiUsd <= 0 || walUsd <= 0)
+        return null;
+    if (!Number.isFinite(suiUsd) || !Number.isFinite(walUsd))
+        return null;
+    return direction === "SUI_TO_WAL" ? suiUsd / walUsd : walUsd / suiUsd;
+}
+/**
+ * The most SUI a swap may take in: balance minus the gas budget the person set, never negative.
+ * Not a fixed reserve — the person chose the budget, so that exact figure is what is kept back.
+ */
+export function maxSwappableSuiMist(suiBalanceMist, gasBudgetMist) {
+    const max = suiBalanceMist - gasBudgetMist;
+    return max > 0n ? max : 0n;
+}
+/**
+ * Every extreme in one trade, in reading order. Empty means ordinary. A budget of null means the
+ * person set none (the SDK will), so there is no fee band to judge; a deviation of null means no
+ * market price was available, which is reported as unknown by the surface, never as "fine".
+ */
+export function swapExtremes(input) {
+    const out = [];
+    const slip = slippageBand(input.slippageBps);
+    if (slip === "low")
+        out.push("lowSlippage");
+    if (slip === "high")
+        out.push("highSlippage");
+    if (input.budgetMist !== null) {
+        const gas = feeBand(input.budgetMist, input.estimateMist);
+        if (gas === "low")
+            out.push("lowFee");
+        if (gas === "high")
+            out.push("highFee");
+    }
+    if (input.deviationBps !== null && Math.abs(input.deviationBps) > DEVIATION_WARN_BPS) {
+        out.push("deviation");
+    }
+    return out;
+}
+// ── Venue fee arithmetic — what a quote's own numbers say the venue charged ────────────────────
+/** Scale that keeps two decimals of a bps figure through integer arithmetic (10,000 bps × 100). */
+const BPS_SCALE = 1000000n;
+/**
+ * A fee in base units as a rate of the amount put in, in bps with two decimals. Bluefin's quote
+ * reports the fee outright (`fee_amount` + `protocol_fee`); both parts count, or the rate reads
+ * smaller than what is charged. Null when nothing went in.
+ */
+export function feeRateBpsOf(feeUnits, amountInUnits) {
+    if (amountInUnits <= 0n || feeUnits < 0n)
+        return null;
+    return Number((feeUnits * BPS_SCALE) / amountInUnits) / 100;
+}
+/**
+ * The three values a DeepBook quote returns are always (base side, quote side, DEEP needed); which
+ * of the first two is "received" and which is "left over" depends on the direction. Base = WAL,
+ * quote = SUI on the WAL_SUI book.
+ */
+export function deepbookRowFrom(direction, base, quote) {
+    return direction === "SUI_TO_WAL"
+        ? { outUnits: base, leftoverInUnits: quote }
+        : { outUnits: quote, leftoverInUnits: base };
+}
+/**
+ * DeepBook's EFFECTIVE fee rate, measured — there is no constant to read. The same amount is
+ * quoted in two modes: fee taken from the input coin (the mode used, needs no DEEP) and fee paid in
+ * DEEP; the difference is what the input mode kept. ⛔ Outputs alone must not be subtracted:
+ * DeepBook rounds to its lot size and each mode leaves a different remainder, so output per unit
+ * ACTUALLY SPENT is compared (25 WAL measured 0.40% the naive way and 0.127% this way, matching a
+ * 100 SUI trade where rounding vanishes). Integer arithmetic throughout.
+ *
+ * Null, never 0, when it cannot be measured — including a non-positive result, which means the
+ * method broke down (the two modes walked the book to different depths), not that the fee is 0.
+ * DeepBook always charges; "0%" would be a lie.
+ */
+export function measureDeepbookFeeBps(amountInUnits, inputMode, deepMode) {
+    if (deepMode === null)
+        return null;
+    const spentInput = amountInUnits - inputMode.leftoverInUnits;
+    const spentDeep = amountInUnits - deepMode.leftoverInUnits;
+    if (spentInput <= 0n || spentDeep <= 0n)
+        return null;
+    const denominator = deepMode.outUnits * spentInput;
+    if (denominator <= 0n)
+        return null;
+    const numerator = denominator - inputMode.outUnits * spentDeep;
+    if (numerator <= 0n)
+        return null;
+    return Number((numerator * BPS_SCALE) / denominator) / 100;
+}

package/dist/shared/lib/wallet/tip.d.ts

@@ -0,0 +1,14 @@
+/** The dial's right end: 10 %. Above it the value is typed, and confirmed once more. */
+export declare const TIP_DIAL_MAX_TENTHS = 100;
+/** No input goes above this: the whole paid amount (100 %). More than that is a separate gift. */
+export declare const TIP_MAX_TENTHS = 1000;
+/** Above this the person confirms "this share, permanently" once more. Same as the dial's end. */
+export declare const TIP_CONFIRM_ABOVE_TENTHS = 100;
+/** A typed percent (decimals allowed) to integer tenths 0..1000. Not a number → 0 (send nothing), not an error. */
+export declare function tenthsFromPercent(input: number): number;
+/** Tenths → the percent a person reads: 25 → "2.5", 100 → "10". */
+export declare function percentText(tenths: number): string;
+/** `tenths`/10 % of the paid amount (base units), rounded down. 0n when nothing was paid or the share is 0. */
+export declare function tipFromTenths(paidBaseUnits: bigint, tenths: number): bigint;
+/** Does this share need the extra confirmation (a value past the dial's end)? */
+export declare function needsExtraConfirm(tenths: number): boolean;

package/dist/shared/lib/wallet/tip.js

@@ -0,0 +1,34 @@
+// Tip arithmetic: what share of a storage payment goes to the developer as a gift. The screen's
+// dial and the CLI's setting use the same scale — tenths of a percent — with the dial ending at
+// 10 % and anything above typed in and confirmed once more. The payment is in WAL, so the tip is.
+//
+// The default is 0, and 0 sends nothing. Division rounds down, so nothing ever signs one unit
+// more than the screen showed. No network, no React, no translation; `test/tip-math.test.ts`.
+/** The dial's right end: 10 %. Above it the value is typed, and confirmed once more. */
+export const TIP_DIAL_MAX_TENTHS = 100;
+/** No input goes above this: the whole paid amount (100 %). More than that is a separate gift. */
+export const TIP_MAX_TENTHS = 1000;
+/** Above this the person confirms "this share, permanently" once more. Same as the dial's end. */
+export const TIP_CONFIRM_ABOVE_TENTHS = TIP_DIAL_MAX_TENTHS;
+/** A typed percent (decimals allowed) to integer tenths 0..1000. Not a number → 0 (send nothing), not an error. */
+export function tenthsFromPercent(input) {
+    if (!Number.isFinite(input))
+        return 0;
+    return Math.min(TIP_MAX_TENTHS, Math.max(0, Math.round(input * 10)));
+}
+/** Tenths → the percent a person reads: 25 → "2.5", 100 → "10". */
+export function percentText(tenths) {
+    const t = Math.min(TIP_MAX_TENTHS, Math.max(0, Math.round(tenths)));
+    return t % 10 === 0 ? String(t / 10) : (t / 10).toFixed(1);
+}
+/** `tenths`/10 % of the paid amount (base units), rounded down. 0n when nothing was paid or the share is 0. */
+export function tipFromTenths(paidBaseUnits, tenths) {
+    const t = Math.min(TIP_MAX_TENTHS, Math.max(0, Math.round(tenths)));
+    if (paidBaseUnits <= 0n || t === 0 || !Number.isFinite(t))
+        return 0n;
+    return (paidBaseUnits * BigInt(t)) / 1000n;
+}
+/** Does this share need the extra confirmation (a value past the dial's end)? */
+export function needsExtraConfirm(tenths) {
+    return tenths > TIP_CONFIRM_ABOVE_TENTHS;
+}

package/dist/shared/lib/wallet/venue-ids.d.ts

@@ -0,0 +1,23 @@
+/** DeepBook v3's package, per network. Read from `@mysten/deepbook-v3` 1.6.2; the mainnet value is confirmed by real trades. */
+export declare const DEEPBOOK_PACKAGE_IDS: Readonly<Record<"mainnet" | "testnet", string>>;
+/** Bluefin Spot's CURRENT package (mainnet only). A fallback for the browser, a name for the list. */
+export declare const BLUEFIN_PACKAGE_IDS: Readonly<Record<"mainnet" | "testnet", string | null>>;
+/** DeepBook's WAL_SUI order book (base = WAL, quote = SUI). ⚠ The testnet book trades a different WAL. */
+export declare const DEEPBOOK_WAL_SUI_POOLS: Readonly<Record<"mainnet" | "testnet", string>>;
+/** DEEP, DeepBook's own coin — an empty coin of it is passed so the fee comes off the input coin. */
+export declare const DEEP_COIN_TYPES: Readonly<Record<"mainnet" | "testnet", string>>;
+/** Bluefin's UpgradeCap — where the CURRENT package is read from before any quote or swap. */
+export declare const BLUEFIN_UPGRADE_CAP_IDS: Readonly<Record<"mainnet" | "testnet", string | null>>;
+/** Bluefin's GlobalConfig shared object — a swap argument, and what the version check reads. */
+export declare const BLUEFIN_GLOBAL_CONFIG_IDS: Readonly<Record<"mainnet" | "testnet", string | null>>;
+/** Bluefin's WAL/SUI pool, `Pool<WAL, SUI>` (coin_a = WAL, coin_b = SUI). Pinned by address: same-pair empty pools exist. */
+export declare const BLUEFIN_WAL_SUI_POOLS: Readonly<Record<"mainnet" | "testnet", string | null>>;
+/**
+ * Bluefin's sqrt-price limits, ONE STEP INSIDE the protocol's tick range (`tick_math.move`). The
+ * range ends themselves abort a swap (1009) while the quote function accepts them, so a swap built
+ * on the ends shows a good quote and fails on chain. Measured on mainnet, both directions,
+ * 2026-08-03. WAL→SUI passes the minimum, SUI→WAL the maximum; the minimum-out argument is what
+ * protects the person, not this.
+ */
+export declare const BLUEFIN_MIN_SQRT_PRICE: bigint;
+export declare const BLUEFIN_MAX_SQRT_PRICE: bigint;

package/dist/shared/lib/wallet/venue-ids.js

@@ -0,0 +1,53 @@
+// The two exchange packages the wallet's activity list recognises, per network. ⚠ PUBLISHED —
+// copied byte-for-byte into the `nmts` command-line package; keep comments self-contained English.
+//
+// ⛔ VALUES ONLY. Their provenance, what makes them stale and what notices it are written beside
+//    the browser's wallet configuration, which re-exports these and is the one place to read about
+//    them. This file exists so the command-line tool can name an exchange transaction with the SAME
+//    addresses the browser uses, without a second copy that drifts.
+/** DeepBook v3's package, per network. Read from `@mysten/deepbook-v3` 1.6.2; the mainnet value is confirmed by real trades. */
+export const DEEPBOOK_PACKAGE_IDS = {
+    testnet: "0xd874d2417a55bfa6479bffa06ad950fea144ef93a94cc6c49f32b03e386bbb24",
+    mainnet: "0x0e735f8c93a95722efd73521aca7a7652c0bb71ed1daf41b26dfd7d1ff71f748",
+};
+/** Bluefin Spot's CURRENT package (mainnet only). A fallback for the browser, a name for the list. */
+export const BLUEFIN_PACKAGE_IDS = {
+    testnet: null,
+    mainnet: "0xd075338d105482f1527cbfd363d6413558f184dec36d9138a70261e87f486e9c",
+};
+// ── The rest of what a swap needs on chain, per network. Same rule: values only, provenance beside
+//    the browser's wallet configuration. Null = that network has no such thing, and nothing is guessed.
+/** DeepBook's WAL_SUI order book (base = WAL, quote = SUI). ⚠ The testnet book trades a different WAL. */
+export const DEEPBOOK_WAL_SUI_POOLS = {
+    testnet: "0x8c1c1b186c4fddab1ebd53e0895a36c1d1b3b9a77cd34e607bef49a38af0150a",
+    mainnet: "0x81f5339934c83ea19dd6bcc75c52e83509629a5f71d3257428c2ce47cc94d08b",
+};
+/** DEEP, DeepBook's own coin — an empty coin of it is passed so the fee comes off the input coin. */
+export const DEEP_COIN_TYPES = {
+    testnet: "0x36dbef866a1d62bf7328989a10fb2f07d769f4ee587c0de4a0a256e57e0a58a8::deep::DEEP",
+    mainnet: "0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270::deep::DEEP",
+};
+/** Bluefin's UpgradeCap — where the CURRENT package is read from before any quote or swap. */
+export const BLUEFIN_UPGRADE_CAP_IDS = {
+    testnet: null,
+    mainnet: "0xd5b2d2159a78030e6f07e028eb75236693ed7f2f32fecbdc1edb32d3a2079c0d",
+};
+/** Bluefin's GlobalConfig shared object — a swap argument, and what the version check reads. */
+export const BLUEFIN_GLOBAL_CONFIG_IDS = {
+    testnet: null,
+    mainnet: "0x03db251ba509a8d5d8777b6338836082335d93eecbdd09a11e190a1cff51c352",
+};
+/** Bluefin's WAL/SUI pool, `Pool<WAL, SUI>` (coin_a = WAL, coin_b = SUI). Pinned by address: same-pair empty pools exist. */
+export const BLUEFIN_WAL_SUI_POOLS = {
+    testnet: null,
+    mainnet: "0xe60bc7ade245b9f35b49686dfab0a18e5ca9176d49bef1b90f60d67d06315ff0",
+};
+/**
+ * Bluefin's sqrt-price limits, ONE STEP INSIDE the protocol's tick range (`tick_math.move`). The
+ * range ends themselves abort a swap (1009) while the quote function accepts them, so a swap built
+ * on the ends shows a good quote and fails on chain. Measured on mainnet, both directions,
+ * 2026-08-03. WAL→SUI passes the minimum, SUI→WAL the maximum; the minimum-out argument is what
+ * protects the person, not this.
+ */
+export const BLUEFIN_MIN_SQRT_PRICE = 4295048016n + 1n;
+export const BLUEFIN_MAX_SQRT_PRICE = 79226673515401279992447579055n - 1n;

package/dist/standing-tip.d.ts

@@ -0,0 +1,24 @@
+import { type DonationConfig } from "./commands/wallet-donate.ts";
+import type { Network } from "./network.ts";
+import type { SignTransfer } from "./wallet-sign.ts";
+/** The owner's thank-you, in both languages, printed after every gift whatever its size. */
+export declare const THANKS_EN = "Thank you for your gift. Honestly, I did not know anyone would. Thank you.";
+export declare const THANKS_KO = "\uD6C4\uC6D0\uD574 \uC8FC\uC154\uC11C \uC815\uB9D0 \uAC10\uC0AC\uD569\uB2C8\uB2E4. \uC0AC\uC2E4 \uC800\uB294 \uD6C4\uC6D0\uD574 \uC904 \uC0AC\uB78C\uC774 \uC788\uC744 \uAC70\uB77C\uACE0\uB3C4 \uBAB0\uB790\uC2B5\uB2C8\uB2E4. \uC815\uB9D0 \uAC10\uC0AC\uD569\uB2C8\uB2E4.";
+export interface StandingTipInput {
+    server: string;
+    network: Network;
+    code: string;
+    /** The sealed list's settings, as read for the payment. */
+    settings: {
+        tipTenths?: number;
+        tipConsentAt?: number;
+    } | undefined;
+    /** What was just paid for storage, in WAL base units. */
+    paidWalFrost: bigint;
+    say: (line: string) => void;
+    /** Seams for tests. */
+    readDonation?: (server: string) => Promise<DonationConfig>;
+    sign?: SignTransfer;
+}
+/** Send the standing share, if there is one. Returns what happened; never throws past a payment. */
+export declare function standingTipAfter(input: StandingTipInput): Promise<"none" | "sent" | "failed">;

package/dist/standing-tip.js

@@ -0,0 +1,52 @@
+// The standing tip: the share of a storage payment the person set once, sent to the developer
+// after every wallet payment without a question (owner 2026-09-06 · the tier table calls it none).
+//
+// ⛔ IT IS THE PERSON'S STANDING CHOICE, READ FROM THE SEALED FILE LIST — the same place the
+//    browser writes it — and it exists only where two things are both true: a share above 0, and
+//    the gift terms agreed to. Nothing here asks; `nmts tip` is where the asking happened.
+//
+// ⛔ A SECOND, SEPARATE TRANSACTION, after the payment is done, never inside it: a gift that fails
+//    must not fail the storage purchase. A failure here is said and does not change the exit code
+//    of the payment — the storage is bought either way.
+//
+// ⛔ OUTSIDE THE WALLET UNLOCK AND ITS CEILING, like every gift (`wallet donate`): the unlock is what
+//    lets a PROGRAM sign for storage; a tip is the person's own standing instruction.
+import { request } from "./api.js";
+import { asDonationConfig } from "./commands/wallet-donate.js";
+import { isValidSuiAddress } from "./shared/lib/wallet/send-rules.js";
+import { percentText, tipFromTenths } from "./shared/lib/wallet/tip.js";
+import { coinAmount, walCoinType } from "./wallet.js";
+/** The owner's thank-you, in both languages, printed after every gift whatever its size. */
+export const THANKS_EN = "Thank you for your gift. Honestly, I did not know anyone would. Thank you.";
+export const THANKS_KO = "후원해 주셔서 정말 감사합니다. 사실 저는 후원해 줄 사람이 있을 거라고도 몰랐습니다. 정말 감사합니다."; // shown in Korean
+/** Send the standing share, if there is one. Returns what happened; never throws past a payment. */
+export async function standingTipAfter(input) {
+    const tenths = input.settings?.tipTenths ?? 0;
+    if (tenths <= 0 || input.settings?.tipConsentAt === undefined || input.paidWalFrost <= 0n)
+        return "none";
+    const amount = tipFromTenths(input.paidWalFrost, tenths);
+    if (amount <= 0n)
+        return "none";
+    try {
+        const config = await (input.readDonation ?? (async (base) => asDonationConfig(await request(base, "/api/donation"))))(input.server);
+        if (!config.sendEnabled || !config.walEnabled || !isValidSuiAddress(config.devAddress)) {
+            input.say(`  Your standing ${percentText(tenths)} % gift was not sent: gifts in WAL are not open right now.`);
+            return "failed";
+        }
+        const sign = input.sign ?? (await import("./wallet-sign.js")).signTransfer;
+        const digest = await sign({
+            network: input.network,
+            code: input.code,
+            shape: { coin: "WAL", amountBaseUnits: amount, destination: config.devAddress, walType: walCoinType(input.network) },
+        });
+        input.say(`  Your standing ${percentText(tenths)} % gift — ${coinAmount(amount)} WAL — went to the developer. Transaction ${digest}`);
+        input.say(`  ${THANKS_EN}`);
+        input.say(`  ${THANKS_KO}`);
+        return "sent";
+    }
+    catch (error) {
+        input.say(`  Your standing ${percentText(tenths)} % gift was not sent: ${error instanceof Error ? error.message : String(error)}`);
+        input.say(`  The storage payment above is unaffected.`);
+        return "failed";
+    }
+}