@needmoretruth/nmts-cli 0.17.2 → 0.34.2

package/dist/wallet-sign.js

@@ -0,0 +1,317 @@
+// ⛔ THE ONE FILE IN THIS TOOL THAT SIGNS. Everything it can do moves real assets and cannot be
+//    reversed by anybody, including NMTS. It signs FIVE SHAPES and no others: extending a file's
+//    storage (`signExtension`), sending SUI or WAL to an address (`signTransfer`), swapping one for
+//    the other on a venue (`signSwap`), and the two halves of a wallet-paid upload — registering one
+//    part's blob (`signBlobRegister`, which buys the storage or binds a held resource and pays the
+//    relay's tip) and certifying it (`signBlobCertify`, gas only). Another transaction shape is a
+//    decision made here, in the open — the test pins the export list.
+//
+// ⛔ AND ONE THING THAT IS NOT A TRANSACTION. `signMessage` signs a short text under the
+//    personal-message intent: it moves nothing, it cannot be replayed as a transaction, and it
+//    exists so somebody can prove an address is theirs — all the hall of fame asks for.
+//
+// ⛔ IT IS REACHED FROM `commands/extend.ts`, `commands/wallet-send.ts`, `commands/wallet-donate.ts`,
+//    `commands/wallet-swap.ts` and `upload-wallet.ts` (the wallet rail `commands/put-wallet.ts`
+//    drives), each after the price, the fee and the balances have been read and printed, and (a
+//    gift excepted) after `requireWalletGrant(…)`. Nothing else imports it, and it is loaded lazily
+//    so that a run which does not spend never even brings the code into memory.
+//
+// ⛔ NO KEY LEAVES THIS FILE. `wallet.ts` states the rule for the whole tool — no function returns
+//    a seed, a private key or a keypair — and this file is the one exception to the reason for it
+//    (something has to hold a key to sign) rather than to the rule itself: the keypair is built
+//    inside a function, asked one question, and dropped. ⚠ `@mysten/sui` keeps the secret inside
+//    its own object with no method that clears it, exactly as it does in the browser's worker; what
+//    is controlled here is lifetime. The buffers this file makes — the derived material, the wallet
+//    root, the seed — are wiped on every path out, failures included.
+//
+// ⛔ THE DERIVATION IS THE ENGINE'S, AT THE INDEX THE BROWSER USES. A second derivation written
+//    here would be free to drift from the one `nmts wallet address` prints, and the way that
+//    surfaces is a transaction signed by a wallet the person has never funded.
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { Transaction } from "@mysten/sui/transactions";
+import { assertUsableCode } from "./account.js";
+import { DERIVED, loadCrypto } from "./crypto.js";
+import { NmtsError } from "./errors.js";
+import { walrusClient } from "./extend-chain.js";
+import { transferTransaction } from "./wallet-send-chain.js";
+import { storageOpTransaction } from "./storage-control-chain.js";
+import { swapTransaction } from "./wallet-swap-chain.js";
+import { isRecord } from "./guards.js";
+import { certifyTransaction, createdBlob, payingClient, registerTransaction, } from "./upload-wallet-chain.js";
+import { BUILT_IN_WALLET_INDEX } from "./wallet.js";
+/**
+ * The keypair the NMTS key derives.
+ *
+ * ⛔ NOT EXPORTED. A caller that could hold this could sign anything, and the whole of this tool's
+ *    story about the wallet is that one command signs one shape of transaction.
+ */
+async function keypairFor(code) {
+    // The one refusal text for a malformed code lives in `account.ts`, so a typo fails here the same
+    // way it fails everywhere else in this tool rather than as an engine error.
+    await assertUsableCode(code);
+    const glue = await loadCrypto();
+    let bytes = null;
+    let derived = null;
+    let root = null;
+    let seed = null;
+    try {
+        bytes = glue.account_code_parse(code);
+        // ⛔ THIS BUFFER IS EVERY KEY IN THE ACCOUNT, not just the wallet root: the sign-in secret, the
+        //    key that opens the files, the key that opens the file list.
+        derived = glue.kdf_derive(bytes);
+        const [from, to] = DERIVED.walletRoot;
+        root = derived.slice(from, to);
+        seed = glue.wallet_seed_for(root, BUILT_IN_WALLET_INDEX);
+        return Ed25519Keypair.fromSecretKey(seed);
+    }
+    catch (error) {
+        if (error instanceof NmtsError)
+            throw error;
+        // ⛔ An engine message about a code can carry the code (`errors.ts`), so it is never passed on.
+        throw new NmtsError("The NMTS key could not be read on this machine.", { exitCode: 1 });
+    }
+    finally {
+        seed?.fill(0);
+        root?.fill(0);
+        derived?.fill(0);
+        bytes?.fill(0);
+    }
+}
+/**
+ * The address this tool would sign as.
+ *
+ * ⛔ IT EXISTS TO BE HELD AGAINST `walletAddress`. That function is what `nmts wallet address`
+ *    prints and what somebody funds; this one is what a transaction would actually be signed by.
+ *    Nothing else in this package proves the two are the same wallet, and the failure if they ever
+ *    part is silent — a signature from an address with nothing in it, or worse, money sent to an
+ *    address that signs nothing. A test compares them, offline, for free.
+ */
+export async function signerAddress(code) {
+    return (await keypairFor(code)).toSuiAddress();
+}
+/**
+ * Extend every listed blob by `epochs`, in ONE transaction, signed by the account's own wallet.
+ *
+ * ONE SIGNATURE FOR ALL OF IT: `extendBlob` returns a transaction fragment, so every blob a file
+ * sits on goes into the same transaction. A multi-part file is one payment and one gas fee, not
+ * five — and a partial extension would buy nothing, because one expired blob is enough to make the
+ * file unreadable.
+ *
+ * ⛔ THE IDS ARE DE-DUPLICATED. Naming the same blob twice pays for the same epochs twice.
+ *
+ * ⚠ A FAILURE HERE IS NOT PROOF THAT NOTHING HAPPENED. A refusal from the node, a timeout, a
+ *   connection that dropped after the bytes went out — none of them say whether the transaction
+ *   was executed. The caller re-reads the chain rather than offering a second attempt against
+ *   numbers it read before.
+ */
+export const signExtension = async ({ network, code, objectIds, epochs }) => {
+    const unique = [...new Set(objectIds)];
+    if (unique.length === 0) {
+        throw new NmtsError("There is nothing on this file that can be extended.", { exitCode: 4 });
+    }
+    if (!Number.isSafeInteger(epochs) || epochs <= 0) {
+        throw new NmtsError("An extension must be a positive whole number of epochs.", { exitCode: 2 });
+    }
+    const client = walrusClient(network);
+    const keypair = await keypairFor(code);
+    const tx = new Transaction();
+    // The sender must be set before the fragments resolve: paying with the SDK's default coin
+    // selection picks the WAL coins from the sender's own address.
+    tx.setSender(keypair.toSuiAddress());
+    for (const blobObjectId of unique) {
+        tx.add(client.walrus.extendBlob({ blobObjectId, epochs }));
+    }
+    const result = await client.signAndExecuteTransaction({
+        transaction: tx,
+        signer: keypair,
+        options: { showEffects: true },
+    });
+    // ⛔ A DIGEST IS NOT A SUCCESS. A transaction that was executed and FAILED still has one, and the
+    //    gas for it is still gone; recording it as an extension would move the drive's expiry date
+    //    over storage nobody bought. The status is asked for above and read here.
+    const effects = result.effects;
+    const status = isRecord(effects) ? effects["status"] : undefined;
+    const outcome = isRecord(status) ? status["status"] : undefined;
+    if (outcome === "failure") {
+        const why = isRecord(status) ? status["error"] : undefined;
+        throw new NmtsError(`The storage network refused the extension: ${typeof why === "string" ? why : "no reason was given"}.`, {
+            exitCode: 1,
+            nextStep: `The storage was NOT extended and the file still ends when it did. The transaction fee ` +
+                `was spent. The usual causes are too little WAL or SUI in this account's wallet — ` +
+                `\`nmts wallet\` shows both — or a length the network will no longer sell.`,
+        });
+    }
+    // ⛔ SUCCESS IS ALREADY KNOWN — the effects above said so. This wait is for what happens NEXT:
+    //    the server is told the digest, `nmts wallet` is run, the browser's activity list opens —
+    //    and a full node that has not indexed the transaction yet answers those as if nothing
+    //    happened. Waiting until it is readable is what the browser's signers do. A wait that times
+    //    out changes nothing about what was signed, so it is not an error of this extension.
+    await client.waitForTransaction({ digest: result.digest }).catch(() => undefined);
+    return result.digest;
+};
+/**
+ * Send SUI or WAL to one address, in ONE transaction, signed by the account's own wallet.
+ *
+ * ⛔ THE TRANSACTION IS BUILT BY `wallet-send-chain.ts`, the same builder the fee was measured
+ *    with, so what is signed is what was priced. The destination is whatever the caller validated
+ *    (`send-rules.ts`) — nothing here checks it again, and nothing can take it back.
+ *
+ * ⚠ A FAILURE HERE IS NOT PROOF THAT NOTHING HAPPENED — the same words as the extension above.
+ */
+export const signTransfer = async ({ network, code, shape }) => {
+    const client = walrusClient(network);
+    const keypair = await keypairFor(code);
+    const tx = transferTransaction({ ...shape, sender: keypair.toSuiAddress() });
+    const result = await client.signAndExecuteTransaction({
+        transaction: tx,
+        signer: keypair,
+        options: { showEffects: true },
+    });
+    const effects = result.effects;
+    const status = isRecord(effects) ? effects["status"] : undefined;
+    const outcome = isRecord(status) ? status["status"] : undefined;
+    if (outcome === "failure") {
+        const why = isRecord(status) ? status["error"] : undefined;
+        throw new NmtsError(`The chain refused the transfer: ${typeof why === "string" ? why : "no reason was given"}.`, {
+            exitCode: 1,
+            nextStep: `Nothing was sent. The transaction fee was spent. The usual cause is a balance that moved ` +
+                `between reading it and signing — \`nmts wallet\` shows both balances now.`,
+        });
+    }
+    await client.waitForTransaction({ digest: result.digest }).catch(() => undefined);
+    return result.digest;
+};
+/**
+ * Sign one short message with the account's own wallet. NOT a transaction: nothing moves.
+ *
+ * ⛔ THE MESSAGE IS THE CALLER'S, WHOLE AND UNCHANGED — the server rebuilds the same bytes from
+ *    the fields it was sent, so a byte added here would invalidate every signature this tool
+ *    makes. `signPersonalMessage` and not `sign`: that intent is the domain separator which stops
+ *    signed text from ever being read as a transaction this wallet authorised.
+ */
+export const signMessage = async ({ code, message }) => {
+    const keypair = await keypairFor(code);
+    const { signature } = await keypair.signPersonalMessage(new TextEncoder().encode(message));
+    return signature;
+};
+/**
+ * Swap SUI for WAL or WAL for SUI on the named venue, in ONE transaction, signed by the account's
+ * own wallet. Every output goes back to the signer — DeepBook's three coins are sent there by this
+ * transaction, Bluefin's by its own entry function — so there is no destination to get wrong.
+ *
+ * ⛔ THE TRANSACTION IS BUILT BY `wallet-swap-chain.ts`, the same builder the fee was measured with,
+ *    on the same Bluefin package the quote used. The minimum-out in the shape is what protects the
+ *    person: the chain refuses a swap that would give less, and the fee for that refusal is spent.
+ *
+ * ⚠ A FAILURE HERE IS NOT PROOF THAT NOTHING HAPPENED — the same words as the extension above.
+ */
+export const signSwap = async ({ network, code, shape }) => {
+    const client = walrusClient(network);
+    const keypair = await keypairFor(code);
+    const tx = swapTransaction({ ...shape, network, sender: keypair.toSuiAddress() });
+    const result = await client.signAndExecuteTransaction({
+        transaction: tx,
+        signer: keypair,
+        options: { showEffects: true },
+    });
+    const refused = refusedBecause(result);
+    if (refused !== null) {
+        throw new NmtsError(`The chain refused the swap: ${refused}.`, {
+            exitCode: 1,
+            nextStep: `Nothing was swapped. The transaction fee was spent. The usual causes are a price that moved ` +
+                `past the minimum between the quote and the signature — quote again, or allow more slippage — ` +
+                `or a balance that moved. \`nmts wallet\` shows both balances now.`,
+        });
+    }
+    await client.waitForTransaction({ digest: result.digest }).catch(() => undefined);
+    return result.digest;
+};
+/** What a refused execution said, or null when the effects say it went through. */
+function refusedBecause(result) {
+    const effects = isRecord(result) ? result["effects"] : undefined;
+    const status = isRecord(effects) ? effects["status"] : undefined;
+    if (!isRecord(status) || status["status"] !== "failure")
+        return null;
+    const why = status["error"];
+    return typeof why === "string" ? why : "no reason was given";
+}
+/**
+ * Register ONE part's blob, signed by the account's own wallet: the relay's tip, then the storage
+ * — bought for `epochs`, or a resource the wallet already holds, cut to fit first if asked.
+ *
+ * ⛔ THE TRANSACTION IS BUILT BY `upload-wallet-chain.ts`, the same builder the fee was measured
+ *    with, so what is signed is what was priced. What comes back is what the commit and the resume
+ *    need: the digest the relay checks its tip in, the blob object, and the epoch the chain says
+ *    the storage ends at.
+ *
+ * ⚠ A FAILURE HERE IS NOT PROOF THAT NOTHING HAPPENED — the same words as the extension above.
+ *   The caller keeps its record and re-reads it rather than registering again.
+ */
+export const signBlobRegister = async ({ network, code, relayUrl, ...shape }) => {
+    const client = payingClient(network, relayUrl);
+    const keypair = await keypairFor(code);
+    const tx = await registerTransaction(client, network, { ...shape, sender: keypair.toSuiAddress() });
+    const result = await client.signAndExecuteTransaction({
+        transaction: tx,
+        signer: keypair,
+        options: { showEffects: true, showObjectChanges: true },
+    });
+    const refused = refusedBecause(result);
+    if (refused !== null) {
+        throw new NmtsError(`The storage network refused the registration: ${refused}.`, {
+            exitCode: 1,
+            nextStep: `Nothing is stored and no storage was bought. The transaction fee was spent. The usual causes ` +
+                `are too little WAL or SUI in this account's wallet — \`nmts wallet\` shows both — or a held ` +
+                `resource too small for the part once encoded.`,
+        });
+    }
+    await client.waitForTransaction({ digest: result.digest }).catch(() => undefined);
+    const blob = await createdBlob(client, result.objectChanges);
+    return { digest: result.digest, ...blob };
+};
+/** Certify ONE registered part from the relay's certificate. Gas only; nothing else leaves the wallet. */
+export const signBlobCertify = async ({ network, code, relayUrl, ...shape }) => {
+    const client = payingClient(network, relayUrl);
+    const keypair = await keypairFor(code);
+    const tx = certifyTransaction(client, shape);
+    tx.setSender(keypair.toSuiAddress());
+    const result = await client.signAndExecuteTransaction({
+        transaction: tx,
+        signer: keypair,
+        options: { showEffects: true },
+    });
+    const refused = refusedBecause(result);
+    if (refused !== null) {
+        throw new NmtsError(`The storage network refused the certification: ${refused}.`, {
+            exitCode: 1,
+            nextStep: `The storage is bought and the bytes are on the network; only the certification failed, and ` +
+                `its fee was spent. Running the same command again certifies again and buys nothing.`,
+        });
+    }
+    await client.waitForTransaction({ digest: result.digest }).catch(() => undefined);
+    return result.digest;
+};
+/**
+ * Cut, join or hand over a storage resource, in ONE transaction, signed by the account's own wallet.
+ *
+ * ⛔ THE TRANSACTION IS BUILT BY `storage-control-chain.ts`, the same builder the dry run priced,
+ *    so what is signed is what was reviewed. A failed execution still has a digest and still
+ *    spent its gas, so the status is read and a failure is said as one.
+ */
+export const signStorageOp = async ({ network, code, shape, walrusPackageId }) => {
+    const client = walrusClient(network);
+    const keypair = await keypairFor(code);
+    const tx = storageOpTransaction(shape, { walrusPackageId, sender: keypair.toSuiAddress() });
+    const result = await client.signAndExecuteTransaction({ transaction: tx, signer: keypair, options: { showEffects: true } });
+    const effects = result.effects;
+    const status = isRecord(effects) ? effects["status"] : undefined;
+    if (isRecord(status) && status["status"] === "failure") {
+        const why = status["error"];
+        throw new NmtsError(`The chain refused it: ${typeof why === "string" ? why : "no reason was given"}.`, {
+            exitCode: 1,
+            nextStep: "Nothing changed on the resource. The transaction fee was spent.",
+        });
+    }
+    await client.waitForTransaction({ digest: result.digest }).catch(() => undefined);
+    return result.digest;
+};

package/dist/wallet-storage-chain.d.ts

@@ -0,0 +1,3 @@
+import type { StorageRead } from "./commands/wallet-storage.ts";
+import type { Network } from "./network.ts";
+export declare function readWalletStorage(network: Network, address: string): Promise<StorageRead>;

package/dist/wallet-storage-chain.js

@@ -0,0 +1,20 @@
+// The live read behind `nmts wallet storage`: the resources one address holds, and the epoch.
+//
+// ⛔ READ ONLY, and the reader is the browser's (`shared/lib/storage-control/chain.ts`). The epoch
+//    comes from the same window read `nmts extend` prices with; when that read fails the list is
+//    still printed, without the "usable now" judgement, rather than not at all.
+import { SuiJsonRpcClient } from "@mysten/sui/jsonRpc";
+import { MAINNET_WALRUS_PACKAGE_CONFIG, TESTNET_WALRUS_PACKAGE_CONFIG } from "@mysten/walrus";
+import { extendReads } from "./extend-chain.js";
+import { readOwnedStorage, readStorageType } from "./shared/lib/storage-control/chain.js";
+import { suiRpcTransport } from "./sui-rpc.js";
+export async function readWalletStorage(network, address) {
+    const client = new SuiJsonRpcClient({ network, transport: suiRpcTransport(network) });
+    const walrus = network === "mainnet" ? MAINNET_WALRUS_PACKAGE_CONFIG : TESTNET_WALRUS_PACKAGE_CONFIG;
+    const [type, window] = await Promise.all([
+        readStorageType(client, walrus.systemObjectId),
+        extendReads(network).readWindow(),
+    ]);
+    const items = await readOwnedStorage(client, address, type);
+    return { items, currentEpoch: window?.clock.current ?? null };
+}

package/dist/wallet-swap-chain.d.ts

@@ -0,0 +1,52 @@
+import { Transaction } from "@mysten/sui/transactions";
+import type { Network } from "./network.ts";
+import type { SwapDirection, SwapVenue } from "./shared/lib/wallet/swap-rules.ts";
+import { type WalletBalances } from "./wallet.ts";
+import { type VenueQuote } from "./wallet-swap-quote.ts";
+/** Where a swap runs: one of the two mainnet venues, or the official testnet facility. */
+export type SwapRail = SwapVenue | "exchange";
+/** Bluefin's addresses, with the package RESOLVED and version-checked on chain, never assumed. */
+export interface BluefinBinding {
+    packageId: string;
+    globalConfigId: string;
+    poolId: string;
+}
+/** The testnet facility: its object, the package its type names, and its rate (WAL per SUI, as a fraction). */
+export interface ExchangeFacility {
+    objectId: string;
+    packageId: string;
+    rateWal: bigint;
+    rateSui: bigint;
+}
+export interface SwapShape {
+    venue: SwapRail;
+    direction: SwapDirection;
+    amountInUnits: bigint;
+    /** The least to accept, or the chain refuses the swap. The facility has no such argument: 0n. */
+    minOutUnits: bigint;
+    /** A gas ceiling, or undefined to let the SDK set one from its own dry run. */
+    gasBudgetMist?: bigint | undefined;
+    /** Present exactly when `venue` is bluefin: the signature uses the package the quote used. */
+    bluefin?: BluefinBinding | undefined;
+    /** Present exactly when `venue` is exchange. */
+    exchange?: ExchangeFacility | undefined;
+}
+/** The rails a network has. Testnet's DeepBook book trades a different WAL, and Bluefin has none. */
+export declare function railsFor(network: Network): readonly SwapRail[];
+export declare function swapTransaction(input: SwapShape & {
+    network: Network;
+    sender: string;
+}): Transaction;
+/** What `commands/wallet-swap.ts` reads before it prints a review. */
+export interface SwapReads {
+    readWallet(address: string): Promise<WalletBalances>;
+    /** Bluefin's current package, version-checked. Throws when no known package passes. */
+    resolveBluefin(): Promise<BluefinBinding>;
+    /** The testnet facility and its rate. Throws off testnet, or when the object cannot be read. */
+    readExchange(): Promise<ExchangeFacility>;
+    /** One venue's answer now. Throws when it does not answer — never a number in its place. */
+    quote(venue: SwapVenue, direction: SwapDirection, amountInUnits: bigint, bluefin: BluefinBinding | null): Promise<VenueQuote>;
+    /** The fee in MIST measured by dry-running this exact swap, or null when it could not be. */
+    estimateFee(shape: SwapShape, sender: string): Promise<bigint | null>;
+}
+export declare function swapReads(network: Network): SwapReads;

package/dist/wallet-swap-chain.js

@@ -0,0 +1,186 @@
+// The swap transaction and its live reads: the wallet's balances, Bluefin's current package, the
+// testnet facility's rate, and the fee a dry run measures. The quotes live next door in
+// `wallet-swap-quote.ts`; both files read, and only `wallet-sign.ts` signs.
+//
+// ⛔ ONE BUILDER FOR THE FEE AND THE SIGNATURE. `estimateFee` and `wallet-sign.ts` both call
+//    `swapTransaction`, so the fee printed is the fee of the transaction that is then signed.
+//
+// ⛔ THE SHAPES ARE THE BROWSER'S, CALL FOR CALL. DeepBook: `pool::swap_exact_quote_for_base` (SUI→WAL)
+//    or `swap_exact_base_for_quote` (WAL→SUI) with an EMPTY DEEP coin so the fee comes off the input
+//    coin, and all THREE outputs (base, quote, DEEP) sent back to the signer — Move cannot drop a
+//    coin, so a forgotten one aborts the whole transaction. Bluefin: `gateway::swap_assets`, which
+//    sends its outputs to the sender itself; type arguments always in pool order [WAL, SUI], the
+//    direction carried by the `a2b` flag, and a sqrt-price limit one step inside the tick range
+//    (the exact end aborts). Testnet: the official Walrus facility `wal_exchange::exchange_all_for_wal`,
+//    SUI→WAL only, whose package is read off the Exchange object's own type. The ids come from
+//    `shared/lib/wallet/venue-ids.ts`, copied byte-for-byte from the browser.
+//
+// ⛔ OUR SHARE IS ZERO. No NMTS address, no fee argument, no output of ours in any of the three.
+import { coinWithBalance, Transaction } from "@mysten/sui/transactions";
+import { TESTNET_WALRUS_PACKAGE_CONFIG } from "@mysten/walrus";
+import { walrusClient, netGasFee } from "./extend-chain.js";
+import { isRecord } from "./guards.js";
+import { BLUEFIN_GLOBAL_CONFIG_IDS, BLUEFIN_MAX_SQRT_PRICE, BLUEFIN_MIN_SQRT_PRICE, BLUEFIN_PACKAGE_IDS, BLUEFIN_UPGRADE_CAP_IDS, BLUEFIN_WAL_SUI_POOLS, DEEP_COIN_TYPES, DEEPBOOK_PACKAGE_IDS, DEEPBOOK_WAL_SUI_POOLS, } from "./shared/lib/wallet/venue-ids.js";
+import { readBalances, SUI_COIN_TYPE, walCoinType } from "./wallet.js";
+import { chainReader } from "./wallet-chain.js";
+import { quoteVenue, QUOTE_SENDER } from "./wallet-swap-quote.js";
+/** The rails a network has. Testnet's DeepBook book trades a different WAL, and Bluefin has none. */
+export function railsFor(network) {
+    return network === "mainnet" ? ["deepbook", "bluefin"] : ["exchange"];
+}
+export function swapTransaction(input) {
+    const tx = new Transaction();
+    tx.setSender(input.sender);
+    const walType = walCoinType(input.network);
+    const a2b = input.direction === "WAL_TO_SUI";
+    const coinIn = a2b
+        ? tx.add(coinWithBalance({ balance: input.amountInUnits, type: walType }))
+        : tx.splitCoins(tx.gas, [input.amountInUnits])[0];
+    if (input.venue === "deepbook") {
+        const deepIn = tx.moveCall({ target: "0x2::coin::zero", typeArguments: [DEEP_COIN_TYPES[input.network]] });
+        const swapped = tx.moveCall({
+            target: `${DEEPBOOK_PACKAGE_IDS[input.network]}::pool::${a2b ? "swap_exact_base_for_quote" : "swap_exact_quote_for_base"}`,
+            typeArguments: [walType, SUI_COIN_TYPE],
+            arguments: [tx.object(DEEPBOOK_WAL_SUI_POOLS[input.network]), coinIn, deepIn, tx.pure.u64(input.minOutUnits), tx.object.clock()],
+        });
+        // All three outputs — base, quote, DEEP — go back to the signer. The result is indexed, and an
+        // index is typed as possibly absent; nothing below can build a transfer of fewer than three.
+        const outputs = [swapped[0], swapped[1], swapped[2]].filter((coin) => coin !== undefined);
+        if (outputs.length !== 3)
+            throw new Error("DeepBook's swap did not yield its three outputs.");
+        tx.transferObjects(outputs, input.sender);
+    }
+    else if (input.venue === "bluefin") {
+        if (input.bluefin === undefined)
+            throw new Error("A Bluefin swap needs its resolved package first.");
+        const coinZero = tx.moveCall({ target: "0x2::coin::zero", typeArguments: [a2b ? SUI_COIN_TYPE : walType] });
+        tx.moveCall({
+            target: `${input.bluefin.packageId}::gateway::swap_assets`,
+            typeArguments: [walType, SUI_COIN_TYPE],
+            arguments: [
+                tx.object.clock(),
+                tx.object(input.bluefin.globalConfigId),
+                tx.object(input.bluefin.poolId),
+                a2b ? coinIn : coinZero,
+                a2b ? coinZero : coinIn,
+                tx.pure.bool(a2b),
+                tx.pure.bool(true),
+                tx.pure.u64(input.amountInUnits),
+                tx.pure.u64(input.minOutUnits),
+                tx.pure.u128(a2b ? BLUEFIN_MIN_SQRT_PRICE : BLUEFIN_MAX_SQRT_PRICE),
+            ],
+        });
+    }
+    else {
+        if (input.exchange === undefined)
+            throw new Error("The testnet exchange needs its object first.");
+        if (a2b)
+            throw new Error("The testnet facility only turns SUI into WAL.");
+        const walOut = tx.moveCall({
+            target: `${input.exchange.packageId}::wal_exchange::exchange_all_for_wal`,
+            arguments: [tx.object(input.exchange.objectId), coinIn],
+        });
+        tx.transferObjects([walOut], input.sender);
+    }
+    if (input.gasBudgetMist !== undefined)
+        tx.setGasBudget(input.gasBudgetMist);
+    return tx;
+}
+const FULL_ADDRESS = /^0x[0-9a-f]{64}$/;
+/** `fields.<name>` of a Move object's content, as a string, or null when the shape differs. */
+function fieldOf(content, name) {
+    const fields = isRecord(content) ? content["fields"] : undefined;
+    return isRecord(fields) ? fields[name] : undefined;
+}
+export function swapReads(network) {
+    const client = walrusClient(network);
+    let bluefin = null;
+    async function livePackage(upgradeCapId) {
+        try {
+            const obj = await client.getObject({ id: upgradeCapId, options: { showContent: true, showType: true } });
+            if (obj.data?.type !== "0x2::package::UpgradeCap")
+                return null;
+            const pkg = fieldOf(obj.data.content, "package");
+            return typeof pkg === "string" && FULL_ADDRESS.test(pkg) ? pkg : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async function versionPasses(packageId, globalConfigId) {
+        try {
+            const tx = new Transaction();
+            tx.moveCall({ target: `${packageId}::config::verify_version`, arguments: [tx.object(globalConfigId)] });
+            const res = await client.devInspectTransactionBlock({ sender: QUOTE_SENDER, transactionBlock: tx });
+            return !res.error;
+        }
+        catch {
+            return false;
+        }
+    }
+    return {
+        async readWallet(address) {
+            return readBalances(chainReader(network, address), walCoinType(network));
+        },
+        async resolveBluefin() {
+            // Memoised for the run, and a failure is not memoised: one refusal must not become "no Bluefin".
+            if (bluefin !== null)
+                return bluefin;
+            const pending = (async () => {
+                const pinned = BLUEFIN_PACKAGE_IDS[network];
+                const capId = BLUEFIN_UPGRADE_CAP_IDS[network];
+                const globalConfigId = BLUEFIN_GLOBAL_CONFIG_IDS[network];
+                const poolId = BLUEFIN_WAL_SUI_POOLS[network];
+                if (pinned === null || capId === null || globalConfigId === null || poolId === null) {
+                    throw new Error(`This tool knows no Bluefin WAL/SUI pool on ${network}.`);
+                }
+                const live = await livePackage(capId);
+                for (const packageId of live === null ? [pinned] : [live, pinned]) {
+                    if (await versionPasses(packageId, globalConfigId))
+                        return { packageId, globalConfigId, poolId };
+                }
+                throw new Error("Bluefin's on-chain version check refused every package address this tool knows.");
+            })();
+            bluefin = pending;
+            pending.catch(() => {
+                if (bluefin === pending)
+                    bluefin = null;
+            });
+            return pending;
+        },
+        async readExchange() {
+            if (network !== "testnet")
+                throw new Error("The built-in SUI→WAL exchange is a testnet-only facility.");
+            const objectId = TESTNET_WALRUS_PACKAGE_CONFIG.exchangeIds[0];
+            if (objectId === undefined)
+                throw new Error("This build names no testnet exchange object.");
+            const obj = await client.getObject({ id: objectId, options: { showContent: true, showType: true } });
+            const type = obj.data?.type;
+            if (typeof type !== "string" || !type.includes("::wal_exchange::Exchange")) {
+                throw new Error(`Object ${objectId} is not a wal_exchange Exchange (type ${type ?? "unknown"}).`);
+            }
+            const rate = fieldOf(obj.data?.content, "rate");
+            const wal = fieldOf(rate, "wal");
+            const sui = fieldOf(rate, "sui");
+            if (typeof wal !== "string" || typeof sui !== "string" || !/^\d+$/.test(wal) || !/^\d+$/.test(sui) || BigInt(sui) === 0n) {
+                throw new Error("The exchange's rate could not be read off its object, so what it would give is unknown.");
+            }
+            return { objectId, packageId: type.split("::")[0] ?? "", rateWal: BigInt(wal), rateSui: BigInt(sui) };
+        },
+        async quote(venue, direction, amountInUnits, binding) {
+            return quoteVenue(client, network, venue, direction, amountInUnits, binding);
+        },
+        async estimateFee(shape, sender) {
+            try {
+                const bytes = await swapTransaction({ ...shape, network, sender }).build({ client });
+                const { effects } = await client.dryRunTransactionBlock({ transactionBlock: bytes });
+                if (effects.status.status !== "success")
+                    return null;
+                return netGasFee(effects.gasUsed);
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}

package/dist/wallet-swap-quote.d.ts

@@ -0,0 +1,22 @@
+import type { walrusClient } from "./extend-chain.ts";
+import type { Network } from "./network.ts";
+import { type SwapDirection, type SwapVenue } from "./shared/lib/wallet/swap-rules.ts";
+/** The zero address: a quote is a read, and a read needs no wallet. */
+export declare const QUOTE_SENDER: string;
+/** One venue's answer, now. Every field was read from the chain this moment; none is a constant. */
+export interface VenueQuote {
+    venue: SwapVenue;
+    /** What comes out AFTER the venue's fee, in base units. */
+    outUnits: bigint;
+    /** The fee this quote carries, in bps (two decimals). Null = could not be measured, not 0. */
+    feeRateBps: number | null;
+    /** Input that would come back unused (DeepBook rounds to its lot size). */
+    leftoverInUnits: bigint;
+}
+type Client = ReturnType<typeof walrusClient>;
+/** One venue's answer now. Bluefin needs its resolved binding; DeepBook needs nothing resolved. */
+export declare function quoteVenue(client: Client, network: Network, venue: SwapVenue, direction: SwapDirection, amountInUnits: bigint, bluefin: {
+    packageId: string;
+    poolId: string;
+} | null): Promise<VenueQuote>;
+export {};