@provablehq/shield-swap-cli 0.7.0

package/dist/mint-6OKWODQG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commands/mint.ts"],"sourcesContent":["/**\n * Mint — open a liquidity position and become the market for a pair.\n *\n * A position deposits both tokens over a price range. While the pool trades\n * inside that range the position earns a cut of every trade; outside it, it earns\n * nothing and sits in one token. The range is chosen here as a percentage either\n * side of the pool's current price, then aligned to the pool's tick spacing —\n * the contract only accepts bounds on that grid.\n *\n * `previewMint` does the arithmetic before anything is signed: the aligned\n * bounds, the liquidity the deposit backs, and — the number that matters — how\n * much of each token is actually consumed. A pair of amounts that balances at\n * one price falls short at another, so the mint takes only what the range needs\n * and the rest stays in the account.\n *\n * Tick insert hints are deliberately not passed. `mint` derives both, and for\n * the upper bound it applies a correction a caller cannot: finalize inserts\n * tick_lower before validating the upper hint, so when no initialized tick sits\n * between the bounds the upper predecessor is the just-inserted lower tick\n * rather than the one visible on chain. Passing an explicit `tickUpperHint`\n * disables that correction and reverts on exactly that case.\n *\n * SPENDS REAL FUNDS with --execute. Without it, prints the plan and stops.\n *\n * Usage:\n *   shield-swap mint --pair USDCx:ETH --percent 1\n *   shield-swap mint --pair USDCx:ETH --percent 1 --execute\n *   shield-swap mint --pair USDCx:ETH --amount0 0.5 --amount1 0.0002 --execute\n *   shield-swap mint --pool <poolKey> --percent 1 --range-pct 10 --execute\n *   shield-swap mint --pair USDCx:ETH --percent 1 --json\n */\nimport { loadSession, formatAmount, namedAmounts, pollUntil } from '../session.js'\nimport { flags, step, done, warn, output, confirmed, run, fail } from '../shared.js'\n\nconst USAGE = `shield-swap mint — open a liquidity position\n\n  --pair <symbol:symbol>        pool to enter, e.g. USDCx:ETH  (or --pool)\n  --pool <poolKey>              exact pool, skipping pair lookup\n  --amount <symbol>:<decimal>   how much of one named token, e.g. USDCx:0.5.\n                                Repeatable, once per side. Prefer this — it does\n                                not depend on knowing the pool's token order\n  --amount0 <decimal>           token0 to commit, in human units\n  --amount1 <decimal>           token1 to commit, in human units\n  --percent <n>                 commit n% of the private balance of both sides\n  --range-pct <n>               range half-width around the price, default 5\n  --network <testnet|mainnet>   default testnet\n  --execute                     actually submit\n  --json                        machine-readable output\n\nEither --percent or at least one amount. A side left unnamed commits its whole\nprivate balance as a ceiling — the plan shows what the range actually consumes,\nwhich is never more than that.\n\n--amount0/--amount1 follow the POOL's token order, which is fixed on chain and\nneed NOT match the order in --pair: naming --pair USDCx:ETH does not make USDCx\nside 0. --amount names the token instead and cannot be transposed. The plan names\nboth symbols either way.`\n\n/**\n * Runs the `mint` subcommand.\n *\n * @param argv Arguments after the subcommand name, as the dispatcher supplies them.\n */\nexport async function main(argv: string[]): Promise<void> {\n  const args = flags(\n    {\n      pair: { type: 'string' },\n      pool: { type: 'string' },\n      amount: { type: 'string', multiple: true },\n      amount0: { type: 'string' },\n      amount1: { type: 'string' },\n      percent: { type: 'string' },\n      'range-pct': { type: 'string' },\n    },\n    USAGE,\n    argv,\n  )\n\n  if (!args.pair && !args.pool) fail(`--pair or --pool is required.\\n\\n${USAGE}`)\n  const bySymbol = (args.amount as string[] | undefined) ?? []\n  const anyAmount = bySymbol.length > 0 || !!args.amount0 || !!args.amount1\n  if (!args.percent && !anyAmount) {\n    fail(`--percent, --amount, --amount0, or --amount1 is required.\\n\\n${USAGE}`)\n  }\n  if (args.percent && anyAmount) {\n    fail(`--percent and the amount flags are alternatives, not both.\\n\\n${USAGE}`)\n  }\n\n  const percent = args.percent ? Number(args.percent) : undefined\n  if (percent !== undefined && (!(percent > 0) || percent > 100)) {\n    fail(`--percent must be greater than 0 and at most 100, got ${args.percent as string}`)\n  }\n\n  /** Basis points of a whole, so `--percent 12.5` is exact rather than rounded to 12. */\n  const share = (total: bigint, pct: number) => (total * BigInt(Math.round(pct * 100))) / 10_000n\n\n  await run(async () => {\n    const { client, account, network } = await loadSession({ network: args.network as string | undefined })\n    done(`session on ${network}`)\n\n    // Resolve the pool first: every amount below is denominated in the pool's own\n    // token0/token1 order, which is fixed on chain and need not match --pair.\n    let poolKey = args.pool as string | undefined\n    if (!poolKey) {\n      const [left, right] = (args.pair as string).split(':')\n      if (!left || !right) throw new Error(`\"${args.pair as string}\" is not symbol:symbol, e.g. USDCx:ETH`)\n      const [a, b] = await Promise.all([client.tokenData(left), client.tokenData(right)])\n      step(`looking for a ${a.symbol}/${b.symbol} pool`)\n      const listed = (await client.api.getPools({ limit: 100 })).data as Array<{\n        key: string\n        token0: string\n        token1: string\n      }>\n      const matches = listed.filter(\n        (pool) =>\n          (pool.token0 === a.id && pool.token1 === b.id) || (pool.token0 === b.id && pool.token1 === a.id),\n      )\n      if (!matches.length) {\n        throw new Error(\n          `no pool pairs ${a.symbol} with ${b.symbol} on ${network}. Run \\`shield-swap pools\\` to see what exists.`,\n        )\n      }\n      // A pair can have several pools, one per fee tier. The deepest is the one a\n      // trader would route through, so it is the one worth providing to.\n      const withDepth = await Promise.all(\n        matches.map(async (pool) => ({ pool, liquidity: (await client.getSlot({ poolKey: pool.key }))?.liquidity ?? 0n })),\n      )\n      withDepth.sort((x, y) => (y.liquidity > x.liquidity ? 1 : y.liquidity < x.liquidity ? -1 : 0))\n      poolKey = withDepth[0]!.pool.key\n      if (matches.length > 1) done(`${matches.length} fee tiers pair them — taking the deepest`)\n    }\n\n    const pool = await client.getPool({ poolKey })\n    if (!pool) throw new Error(`no pool ${poolKey} on ${network} — check the key with \\`shield-swap pools\\`.`)\n\n    // A mint the control gates would reject reverts on finalize and still costs a\n    // fee, so the gates are read before the plan rather than discovered after it.\n    const controls = await client.getTradeControls({ poolKey })\n    if (!controls.tradeable) {\n      throw new Error(\n        `pool ${poolKey} is gated on chain right now (global pause ${controls.globalPaused}, ` +\n          `pool enabled ${controls.poolEnabled}, pair paused ${controls.pairPaused}) — a mint would revert.`,\n      )\n    }\n\n    const tokens = await client.listTokens()\n    const infoOf = (id: string) => tokens.find((token) => token.id === id)\n    const token0 = infoOf(pool.token0)\n    const token1 = infoOf(pool.token1)\n    if (!token0 || !token1) throw new Error(`the registry does not describe both tokens of pool ${poolKey}.`)\n\n    // Private records fund a deposit; the public balance cannot be minted from.\n    step('reading private balances for both sides')\n    const balances = await client.getBalances({ tokens: [token0.id, token1.id] })\n    const held0 = balances[token0.id]?.private ?? 0n\n    const held1 = balances[token1.id]?.private ?? 0n\n    if (held0 === 0n || held1 === 0n) {\n      throw new Error(\n        `an in-range position needs both sides, and this account holds ` +\n          `${formatAmount(held0, token0.decimals, token0.symbol)} and ` +\n          `${formatAmount(held1, token1.decimals, token1.symbol)} privately. Fund the empty side first.`,\n      )\n    }\n\n    // The budget is a ceiling, not the deposit: the preview below reports what the\n    // range consumes out of it.\n    const named = namedAmounts({\n      entries: bySymbol,\n      indexed: [args.amount0 as string | undefined, args.amount1 as string | undefined],\n      tokens: [token0, token1],\n    })\n    const budget0 = percent ? share(held0, percent) : (named.amount0 ?? held0)\n    const budget1 = percent ? share(held1, percent) : (named.amount1 ?? held1)\n    if (budget0 > held0 || budget1 > held1) {\n      throw new Error(\n        `asked to commit ${formatAmount(budget0, token0.decimals, token0.symbol)} / ` +\n          `${formatAmount(budget1, token1.decimals, token1.symbol)} but the account holds ` +\n          `${formatAmount(held0, token0.decimals, token0.symbol)} / ` +\n          `${formatAmount(held1, token1.decimals, token1.symbol)} privately.`,\n      )\n    }\n\n    const rangePercent = args['range-pct'] ? Number(args['range-pct']) : 5\n    step(`pricing a ±${rangePercent}% range against the pool's live price`)\n    const preview = await client.previewMint({\n      poolKey,\n      amount0Desired: budget0,\n      amount1Desired: budget1,\n      rangePercent,\n    })\n    if (preview.liquidity === 0n) {\n      throw new Error(\n        `that budget backs no liquidity over ticks ${preview.tickLower}…${preview.tickUpper} — ` +\n          'commit more, or narrow the range with --range-pct. A mint would cost a fee and open nothing.',\n      )\n    }\n    if (!preview.inRange) {\n      warn(\n        `the pool trades at tick ${preview.tickCurrent}, outside ${preview.tickLower}…${preview.tickUpper}: ` +\n          'this position earns nothing until the price moves into its range, and is funded from one side only',\n      )\n    }\n    if (preview.feeTierSpacing !== null && preview.feeTierSpacing !== preview.tickSpacing) {\n      warn(\n        `the pool's tick spacing (${preview.tickSpacing}) differs from what fee tier ${preview.fee} binds ` +\n          `(${preview.feeTierSpacing}) — the bounds follow the pool, which is what the contract aligns to`,\n      )\n    }\n\n    // Each side is funded from ONE record, not the sum of several, so a balance\n    // large enough in total can still be too fragmented to mint from.\n    const perSide = [\n      { info: token0, needed: preview.amount0, held: held0 },\n      { info: token1, needed: preview.amount1, held: held1 },\n    ]\n    for (const side of perSide) {\n      if (side.needed > side.held) {\n        throw new Error(\n          `the range needs ${formatAmount(side.needed, side.info.decimals, side.info.symbol)} but only ` +\n            `${formatAmount(side.held, side.info.decimals, side.info.symbol)} is held privately.`,\n        )\n      }\n    }\n\n    const planLines: Array<readonly [string, string]> = [\n      ['pool', `${token0.symbol}/${token1.symbol}  fee ${preview.fee}  spacing ${preview.tickSpacing}`],\n      [\n        'range',\n        `ticks ${preview.tickLower}…${preview.tickUpper} (±${rangePercent}%, price at tick ${preview.tickCurrent})`,\n      ],\n      ['status', preview.inRange ? 'in range — earns fees immediately' : 'OUT OF RANGE — earns nothing yet'],\n      ['deposit', formatAmount(preview.amount0, token0.decimals, token0.symbol)],\n      // Empty label: the second side of the same deposit, not a separate step.\n      ['', formatAmount(preview.amount1, token1.decimals, token1.symbol)],\n      [\n        'unused',\n        `${formatAmount(budget0 - preview.amount0, token0.decimals, token0.symbol)} / ` +\n          `${formatAmount(budget1 - preview.amount1, token1.decimals, token1.symbol)} of the budget stays in the account`,\n      ],\n      ['owner', `${account.address} (also the withdrawal address collect pays)`],\n    ]\n    if (!confirmed({ execute: args.execute as boolean | undefined, network, plan: planLines })) {\n      output({ network, submitted: false, poolKey, preview }, () => {})\n      return\n    }\n\n    // Both token programs' sources: the prover cannot discover the dynamically\n    // dispatched IARC20 callees on its own.\n    const imports = await client.resolveDexImports({\n      tokenPrograms: [token0.ammTokenProgram, token1.ammTokenProgram].filter((program): program is string => !!program),\n    })\n\n    step('proving and submitting the mint — this takes a minute or two')\n    // No amount0Min/amount1Min: the contract takes at most the desired amounts, so\n    // a price that moves between the preview and the finalize deposits slightly\n    // less rather than more. A min would turn that into a revert.\n    const minted = await client.mint({\n      poolKey,\n      tickLower: preview.tickLower,\n      tickUpper: preview.tickUpper,\n      amount0Desired: preview.amount0,\n      amount1Desired: preview.amount1,\n      recipient: account.address,\n      withdrawal: account.address,\n      imports,\n    })\n    done(`mint landed: tx ${minted.transactionId}`)\n    if (!minted.positionTokenId) {\n      // Only reachable on a wallet signer without the WASM peer; a local key\n      // always gets the id back as a public output.\n      warn('the position id was not returned — find it with `shield-swap positions`')\n      output({ network, submitted: true, poolKey, transactionId: minted.transactionId, preview }, () => {})\n      return\n    }\n    step(`position ${minted.positionTokenId} — waiting for the positions mapping to catch up`)\n\n    // Mapping writes propagate to reads asynchronously, so the entry is expected\n    // to be absent for a few seconds after the transaction confirms.\n    let onchain: NonNullable<Awaited<ReturnType<typeof client.getPosition>>> | undefined\n    const appeared = await pollUntil(\n      async () => {\n        const position = await client.getPosition({ positionTokenId: minted.positionTokenId! })\n        if (position) onchain = position\n        return position !== null\n      },\n      20,\n      3_000,\n    )\n    if (appeared) done(`chain carries the position with liquidity ${onchain!.liquidity}`)\n    else warn('the position has not appeared in the positions mapping yet — check `shield-swap positions` shortly')\n\n    output(\n      {\n        network,\n        submitted: true,\n        poolKey,\n        positionTokenId: minted.positionTokenId,\n        transactionId: minted.transactionId,\n        tickLower: preview.tickLower,\n        tickUpper: preview.tickUpper,\n        deposited0: preview.amount0,\n        deposited1: preview.amount1,\n        predictedLiquidity: preview.liquidity,\n        liquidity: onchain?.liquidity ?? null,\n      },\n      (data) => {\n        console.log(`\\nPosition ${data.positionTokenId} open on ${token0.symbol}/${token1.symbol}.`)\n        console.log(\n          `Deposited ${formatAmount(data.deposited0, token0.decimals, token0.symbol)} and ` +\n            `${formatAmount(data.deposited1, token1.decimals, token1.symbol)} over ticks ` +\n            `${data.tickLower}…${data.tickUpper}.`,\n        )\n        console.log('Track it with `shield-swap positions`; collect earnings with `shield-swap collect`.')\n      },\n    )\n  })\n}\n"],"mappings":"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","names":["pool"]}

package/dist/pools-NWQNFJ7W.js

@@ -0,0 +1,184 @@
+import {
+  done,
+  flags,
+  output,
+  run,
+  step,
+  table,
+  warn
+} from "./chunk-IBVZHLUT.js";
+import {
+  green,
+  yellow
+} from "./chunk-IHYFMX5A.js";
+import {
+  loadSession
+} from "./chunk-2OT6LZPW.js";
+
+// src/commands/pools.ts
+function formatFee(pips) {
+  return `${(pips / 1e4).toFixed(4).replace(/\.?0+$/, "")}%`;
+}
+var USAGE = `shield-swap pools \u2014 discover tradeable pools
+
+  --network <testnet|mainnet>   default testnet
+  --token <symbol|id>           only pools holding this token
+  --positions                   add this account's stake in each pool
+  --sort <liquidity|fee>        default liquidity
+  --limit <n>                   pools to inspect, default 50
+  --json                        machine-readable output`;
+async function stakePerPool(client, pools) {
+  const owned = await client.getOwnedPositions();
+  const byKey = new Map(pools.map((pool) => [pool.poolKey, pool]));
+  const stakes = /* @__PURE__ */ new Map();
+  let elsewhere = 0;
+  for (const position of owned) {
+    const pool = byKey.get(position.poolKey);
+    if (!pool) {
+      elsewhere += 1;
+      continue;
+    }
+    const stake = stakes.get(position.poolKey) ?? { positions: 0, outOfRange: 0, noChainEntry: 0, liquidity: 0n, shareBps: null };
+    stake.positions += 1;
+    if (position.state === null) {
+      stake.noChainEntry += 1;
+    } else if (position.tickLower <= pool.tick && pool.tick < position.tickUpper) {
+      stake.liquidity += position.state.liquidity;
+    } else stake.outOfRange += 1;
+    stakes.set(position.poolKey, stake);
+  }
+  for (const [poolKey, stake] of stakes) {
+    const active = byKey.get(poolKey)?.liquidity ?? 0n;
+    stake.shareBps = active > 0n ? Number(stake.liquidity * 10000n / active) : null;
+  }
+  return { stakes, elsewhere };
+}
+async function discoverPools(client, options = {}) {
+  const filter = options.token ? await client.tokenData(options.token) : void 0;
+  if (filter) step(`filtering to ${filter.symbol} (${filter.id})`);
+  step("reading the pool index");
+  const listed = (await client.api.getPools({ limit: options.limit ?? 50 })).data;
+  const tokens = await client.listTokens();
+  const infoOf = (id) => tokens.find((token) => token.id === id);
+  const relevant = filter ? listed.filter((pool) => pool.token0 === filter.id || pool.token1 === filter.id) : listed;
+  step(`inspecting ${relevant.length} of ${listed.length} pools on chain`);
+  const summaries = [];
+  for (const pool of relevant) {
+    const [onchain, slot, controls] = await Promise.all([
+      client.getPool({ poolKey: pool.key }),
+      client.getSlot({ poolKey: pool.key }),
+      client.getTradeControls({ poolKey: pool.key })
+    ]);
+    if (!onchain || !slot) continue;
+    const t0 = infoOf(pool.token0);
+    const t1 = infoOf(pool.token1);
+    summaries.push({
+      poolKey: pool.key,
+      token0: { id: pool.token0, symbol: t0?.symbol ?? "?", decimals: t0?.decimals ?? 0 },
+      token1: { id: pool.token1, symbol: t1?.symbol ?? "?", decimals: t1?.decimals ?? 0 },
+      fee: onchain.fee,
+      tickSpacing: slot.tick_spacing,
+      tick: slot.tick,
+      liquidity: slot.liquidity,
+      tradeable: controls.tradeable && slot.liquidity > 0n,
+      ...controls.tradeable ? slot.liquidity > 0n ? {} : { reason: "no liquidity" } : { reason: "paused or gated on chain" }
+    });
+  }
+  return summaries;
+}
+async function main(argv) {
+  const args = flags(
+    {
+      token: { type: "string" },
+      positions: { type: "boolean" },
+      sort: { type: "string" },
+      limit: { type: "string" }
+    },
+    USAGE,
+    argv
+  );
+  await run(async () => {
+    const { client, network } = await loadSession({ network: args.network });
+    done(`session on ${network}`);
+    const pools = await discoverPools(client, {
+      ...args.token ? { token: args.token } : {},
+      ...args.limit ? { limit: Number(args.limit) } : {}
+    });
+    const sorted = args.sort === "fee" ? [...pools].sort((a, b) => a.fee - b.fee) : [...pools].sort((a, b) => b.liquidity > a.liquidity ? 1 : b.liquidity < a.liquidity ? -1 : 0);
+    let stakes;
+    if (args.positions) {
+      step("scanning position records to attribute a stake to each pool");
+      const mine = await stakePerPool(client, sorted);
+      stakes = mine.stakes;
+      if (mine.elsewhere) {
+        warn(
+          `${mine.elsewhere} position(s) are in pools outside this listing \u2014 widen --limit or drop --token to see them`
+        );
+      }
+    }
+    output(
+      {
+        network,
+        pools: sorted.map((pool) => ({
+          ...pool,
+          ...stakes ? { stake: stakes.get(pool.poolKey) ?? null } : {}
+        }))
+      },
+      (data) => {
+        if (!data.pools.length) {
+          console.log(
+            args.token ? `
+No pools hold ${args.token} on ${data.network}. Drop --token to see every pool.` : `
+No pools on ${data.network}.`
+          );
+          return;
+        }
+        const headers = ["PAIR", "FEE", "SPACING", "TICK", "LIQUIDITY", "STATUS", "POOL KEY"];
+        const align = ["left", "right", "right", "right", "right", "left", "left"];
+        if (stakes) {
+          headers.splice(5, 0, "POSITIONS", "MY LIQUIDITY", "SHARE");
+          align.splice(5, 0, "right", "right", "right");
+        }
+        table(
+          headers,
+          data.pools.map((pool) => {
+            const row = [
+              `${pool.token0.symbol}/${pool.token1.symbol}`,
+              formatFee(pool.fee),
+              String(pool.tickSpacing),
+              String(pool.tick),
+              // Liquidity stays raw on purpose: it is not denominated in either
+              // token, so rendering it with a token's decimals would misstate it.
+              pool.liquidity.toString(),
+              // Green reads as "you can trade this now"; a reason is always a
+              // reason it is unavailable, so it takes the warning colour.
+              pool.reason ? yellow(pool.reason) : green("tradeable"),
+              pool.poolKey
+            ];
+            if (stakes) {
+              const stake = stakes.get(pool.poolKey);
+              const notes = stake ? [
+                ...stake.outOfRange ? [`${stake.outOfRange} out`] : [],
+                ...stake.noChainEntry ? [`${stake.noChainEntry} no entry`] : []
+              ] : [];
+              row.splice(
+                5,
+                0,
+                stake ? `${stake.positions}${notes.length ? ` (${notes.join(", ")})` : ""}` : "\u2014",
+                stake && stake.liquidity > 0n ? stake.liquidity.toString() : "\u2014",
+                stake?.shareBps == null ? "\u2014" : `${(stake.shareBps / 100).toFixed(2)}%`
+              );
+            }
+            return row;
+          }),
+          align
+        );
+      }
+    );
+  });
+}
+export {
+  discoverPools,
+  main
+};
+//# sourceMappingURL=pools-NWQNFJ7W.js.map

package/dist/pools-NWQNFJ7W.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commands/pools.ts"],"sourcesContent":["/**\n * Pool discovery — what can be traded, and how deep it is.\n *\n * Lists the pools the API knows, then checks each against chain: the API can\n * list a pool the contract refuses to trade, so the tradeable flag and the live\n * liquidity come from the mappings rather than the index.\n *\n * Reads only. Spends nothing, needs no funded account, and works before setup\n * has run if a state file already carries a key. `--positions` is the exception:\n * it scans the account's own records, which needs a working record scanner.\n *\n * Usage:\n *   shield-swap pools                          # testnet, human table\n *   shield-swap pools --network mainnet        # mainnet\n *   shield-swap pools --token USDCx            # only pools holding this token\n *   shield-swap pools --positions              # add this account's stake per pool\n *   shield-swap pools --sort liquidity         # deepest first (default)\n *   shield-swap pools --limit 10 --json        # machine-readable\n */\nimport { loadSession } from '../session.js'\nimport { flags, step, done, warn, output, run, table } from '../shared.js'\nimport { green, yellow } from '../color.js'\n\n/**\n * Renders a pool's fee tier as a percentage.\n *\n * The contract counts fees in pips out of 1,000,000 (`fee_pips`), so the raw\n * `800` a pool reports is 0.08% rather than 800 of anything a trader recognises.\n * Trailing zeros are dropped so the thinnest tiers stay legible. Pure and local.\n *\n * @param pips The pool's fee, as stored on chain.\n * @returns The tier as a percentage string, e.g. `'0.08%'`.\n */\nfunction formatFee(pips: number): string {\n  return `${(pips / 10_000).toFixed(4).replace(/\\.?0+$/, '')}%`\n}\n\nconst USAGE = `shield-swap pools — discover tradeable pools\n\n  --network <testnet|mainnet>   default testnet\n  --token <symbol|id>           only pools holding this token\n  --positions                   add this account's stake in each pool\n  --sort <liquidity|fee>        default liquidity\n  --limit <n>                   pools to inspect, default 50\n  --json                        machine-readable output`\n\n/** A pool with the chain's opinion of it, not just the index's. */\nexport type PoolSummary = {\n  poolKey: string\n  token0: { id: string; symbol: string; decimals: number }\n  token1: { id: string; symbol: string; decimals: number }\n  fee: number\n  tickSpacing: number\n  tick: number\n  liquidity: bigint\n  tradeable: boolean\n  reason?: string\n}\n\n/**\n * What the account holds in one pool, measured the way the pool measures it.\n *\n * @property positions Position records the account holds in this pool, including\n *   any counted by `noChainEntry`.\n * @property outOfRange How many sit outside the current price. Those earn nothing\n *   and contribute nothing to the pool's active liquidity.\n * @property noChainEntry How many have no entry in the positions mapping — a mint\n *   still finalizing, or one already burned whose record the scanner still serves.\n *   Neither holds liquidity, so they are classified as neither in nor out of range.\n * @property liquidity In-range liquidity only, so it is comparable to the pool's\n *   own figure.\n * @property shareBps In-range liquidity as basis points of the pool's active\n *   liquidity, or `null` when the pool has none to divide by.\n */\nexport type PoolStake = {\n  positions: number\n  outOfRange: number\n  noChainEntry: number\n  liquidity: bigint\n  shareBps: number | null\n}\n\n/**\n * Sums the account's positions per pool, counting only what the pool counts.\n *\n * A position's liquidity is part of a pool's active liquidity only while the\n * price sits inside its range — outside it the position is idle. Summing every\n * position regardless would overstate the account's share of a pool it currently\n * earns nothing from, so out-of-range positions are counted separately rather\n * than added in.\n *\n * Scans the account's records, which needs a record scanner. One scan covers\n * every pool.\n *\n * @param client A composed shield-swap client.\n * @param pools The pools to attribute stakes to. Positions in any other pool are\n *   ignored, and the count of those is returned so the caller can say so.\n * @returns Stakes keyed by pool key, and how many positions fell outside `pools`.\n */\nasync function stakePerPool(\n  client: Awaited<ReturnType<typeof loadSession>>['client'],\n  pools: PoolSummary[],\n): Promise<{ stakes: Map<string, PoolStake>; elsewhere: number }> {\n  const owned = await client.getOwnedPositions()\n  const byKey = new Map(pools.map((pool) => [pool.poolKey, pool]))\n  const stakes = new Map<string, PoolStake>()\n  let elsewhere = 0\n\n  for (const position of owned) {\n    const pool = byKey.get(position.poolKey)\n    if (!pool) {\n      elsewhere += 1\n      continue\n    }\n    const stake =\n      stakes.get(position.poolKey) ??\n      { positions: 0, outOfRange: 0, noChainEntry: 0, liquidity: 0n, shareBps: null }\n    stake.positions += 1\n    if (position.state === null) {\n      // No mapping entry means it holds no liquidity at all, so calling it\n      // in-range would imply it is earning and calling it out-of-range would\n      // imply it could be brought back in. It is neither.\n      stake.noChainEntry += 1\n    } else if (position.tickLower <= pool.tick && pool.tick < position.tickUpper) {\n      // Upper bound exclusive, matching the contract: at exactly tick_upper the\n      // position is already out of range.\n      stake.liquidity += position.state.liquidity\n    } else stake.outOfRange += 1\n    stakes.set(position.poolKey, stake)\n  }\n\n  for (const [poolKey, stake] of stakes) {\n    const active = byKey.get(poolKey)?.liquidity ?? 0n\n    stake.shareBps = active > 0n ? Number((stake.liquidity * 10_000n) / active) : null\n  }\n  return { stakes, elsewhere }\n}\n\n/**\n * Discovers pools and joins each with its chain state.\n *\n * @param client A composed shield-swap client.\n * @param options.token Symbol or id to filter by.\n * @param options.limit Pools to inspect.\n * @returns One summary per pool, deepest first unless sorted otherwise.\n */\nexport async function discoverPools(\n  client: Awaited<ReturnType<typeof loadSession>>['client'],\n  options: { token?: string; limit?: number } = {},\n): Promise<PoolSummary[]> {\n  const filter = options.token ? await client.tokenData(options.token) : undefined\n  if (filter) step(`filtering to ${filter.symbol} (${filter.id})`)\n\n  step('reading the pool index')\n  const listed = (await client.api.getPools({ limit: options.limit ?? 50 })).data as Array<{\n    key: string\n    token0: string\n    token1: string\n  }>\n  const tokens = await client.listTokens()\n  const infoOf = (id: string) => tokens.find((token) => token.id === id)\n\n  const relevant = filter\n    ? listed.filter((pool) => pool.token0 === filter.id || pool.token1 === filter.id)\n    : listed\n  step(`inspecting ${relevant.length} of ${listed.length} pools on chain`)\n\n  const summaries: PoolSummary[] = []\n  for (const pool of relevant) {\n    // Both gates matter and neither is in the index: a pool can be listed and\n    // paused, or listed with no liquidity to trade against.\n    const [onchain, slot, controls] = await Promise.all([\n      client.getPool({ poolKey: pool.key }),\n      client.getSlot({ poolKey: pool.key }),\n      client.getTradeControls({ poolKey: pool.key }),\n    ])\n    if (!onchain || !slot) continue\n\n    const t0 = infoOf(pool.token0)\n    const t1 = infoOf(pool.token1)\n    summaries.push({\n      poolKey: pool.key,\n      token0: { id: pool.token0, symbol: t0?.symbol ?? '?', decimals: t0?.decimals ?? 0 },\n      token1: { id: pool.token1, symbol: t1?.symbol ?? '?', decimals: t1?.decimals ?? 0 },\n      fee: onchain.fee,\n      tickSpacing: slot.tick_spacing,\n      tick: slot.tick,\n      liquidity: slot.liquidity,\n      tradeable: controls.tradeable && slot.liquidity > 0n,\n      ...(controls.tradeable\n        ? slot.liquidity > 0n\n          ? {}\n          : { reason: 'no liquidity' }\n        : { reason: 'paused or gated on chain' }),\n    })\n  }\n  return summaries\n}\n\n/**\n * Runs the `pools` subcommand.\n *\n * @param argv Arguments after the subcommand name, as the dispatcher supplies them.\n */\nexport async function main(argv: string[]): Promise<void> {\n  const args = flags(\n    {\n      token: { type: 'string' },\n      positions: { type: 'boolean' },\n      sort: { type: 'string' },\n      limit: { type: 'string' },\n    },\n    USAGE,\n    argv,\n  )\n\n  await run(async () => {\n    const { client, network } = await loadSession({ network: args.network as string | undefined })\n    done(`session on ${network}`)\n\n    const pools = await discoverPools(client, {\n      ...(args.token ? { token: args.token as string } : {}),\n      ...(args.limit ? { limit: Number(args.limit) } : {}),\n    })\n    const sorted =\n      args.sort === 'fee'\n        ? [...pools].sort((a, b) => a.fee - b.fee)\n        : [...pools].sort((a, b) => (b.liquidity > a.liquidity ? 1 : b.liquidity < a.liquidity ? -1 : 0))\n\n    let stakes: Map<string, PoolStake> | undefined\n    if (args.positions) {\n      step('scanning position records to attribute a stake to each pool')\n      const mine = await stakePerPool(client, sorted)\n      stakes = mine.stakes\n      // Said rather than swallowed: a position in a pool this listing filtered out\n      // is invisible here, and a zero stake would otherwise read as \"none held\".\n      if (mine.elsewhere) {\n        warn(\n          `${mine.elsewhere} position(s) are in pools outside this listing — widen --limit or drop --token to see them`,\n        )\n      }\n    }\n\n    output(\n      {\n        network,\n        pools: sorted.map((pool) => ({\n          ...pool,\n          ...(stakes ? { stake: stakes.get(pool.poolKey) ?? null } : {}),\n        })),\n      },\n      (data) => {\n        if (!data.pools.length) {\n          // A bare header and rule reads as a rendering fault rather than an empty\n          // result, and the filter is the likeliest reason there is nothing to show.\n          console.log(\n            args.token\n              ? `\\nNo pools hold ${args.token as string} on ${data.network}. Drop --token to see every pool.`\n              : `\\nNo pools on ${data.network}.`,\n          )\n          return\n        }\n        const headers = ['PAIR', 'FEE', 'SPACING', 'TICK', 'LIQUIDITY', 'STATUS', 'POOL KEY']\n        const align: Array<'left' | 'right'> = ['left', 'right', 'right', 'right', 'right', 'left', 'left']\n        if (stakes) {\n          // Inserted before POOL KEY, which is long enough to push anything after\n          // it off a narrow terminal.\n          headers.splice(5, 0, 'POSITIONS', 'MY LIQUIDITY', 'SHARE')\n          align.splice(5, 0, 'right', 'right', 'right')\n        }\n        table(\n          headers,\n          data.pools.map((pool) => {\n            const row = [\n              `${pool.token0.symbol}/${pool.token1.symbol}`,\n              formatFee(pool.fee),\n              String(pool.tickSpacing),\n              String(pool.tick),\n              // Liquidity stays raw on purpose: it is not denominated in either\n              // token, so rendering it with a token's decimals would misstate it.\n              pool.liquidity.toString(),\n              // Green reads as \"you can trade this now\"; a reason is always a\n              // reason it is unavailable, so it takes the warning colour.\n              pool.reason ? yellow(pool.reason) : green('tradeable'),\n              pool.poolKey,\n            ]\n            if (stakes) {\n              const stake = stakes.get(pool.poolKey)\n              // Both qualifiers are named in the cell rather than a footnote: a bare\n              // count next to a share of 0.11% invites the reading that every\n              // position is working, when one may be idle and another not on chain.\n              const notes = stake\n                ? [\n                    ...(stake.outOfRange ? [`${stake.outOfRange} out`] : []),\n                    ...(stake.noChainEntry ? [`${stake.noChainEntry} no entry`] : []),\n                  ]\n                : []\n              row.splice(\n                5,\n                0,\n                stake ? `${stake.positions}${notes.length ? ` (${notes.join(', ')})` : ''}` : '—',\n                stake && stake.liquidity > 0n ? stake.liquidity.toString() : '—',\n                stake?.shareBps == null ? '—' : `${(stake.shareBps / 100).toFixed(2)}%`,\n              )\n            }\n            return row\n          }),\n          align,\n        )\n      },\n    )\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAiCA,SAAS,UAAU,MAAsB;AACvC,SAAO,IAAI,OAAO,KAAQ,QAAQ,CAAC,EAAE,QAAQ,UAAU,EAAE,CAAC;AAC5D;AAEA,IAAM,QAAQ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA8Dd,eAAe,aACb,QACA,OACgE;AAChE,QAAM,QAAQ,MAAM,OAAO,kBAAkB;AAC7C,QAAM,QAAQ,IAAI,IAAI,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC;AAC/D,QAAM,SAAS,oBAAI,IAAuB;AAC1C,MAAI,YAAY;AAEhB,aAAW,YAAY,OAAO;AAC5B,UAAM,OAAO,MAAM,IAAI,SAAS,OAAO;AACvC,QAAI,CAAC,MAAM;AACT,mBAAa;AACb;AAAA,IACF;AACA,UAAM,QACJ,OAAO,IAAI,SAAS,OAAO,KAC3B,EAAE,WAAW,GAAG,YAAY,GAAG,cAAc,GAAG,WAAW,IAAI,UAAU,KAAK;AAChF,UAAM,aAAa;AACnB,QAAI,SAAS,UAAU,MAAM;AAI3B,YAAM,gBAAgB;AAAA,IACxB,WAAW,SAAS,aAAa,KAAK,QAAQ,KAAK,OAAO,SAAS,WAAW;AAG5E,YAAM,aAAa,SAAS,MAAM;AAAA,IACpC,MAAO,OAAM,cAAc;AAC3B,WAAO,IAAI,SAAS,SAAS,KAAK;AAAA,EACpC;AAEA,aAAW,CAAC,SAAS,KAAK,KAAK,QAAQ;AACrC,UAAM,SAAS,MAAM,IAAI,OAAO,GAAG,aAAa;AAChD,UAAM,WAAW,SAAS,KAAK,OAAQ,MAAM,YAAY,SAAW,MAAM,IAAI;AAAA,EAChF;AACA,SAAO,EAAE,QAAQ,UAAU;AAC7B;AAUA,eAAsB,cACpB,QACA,UAA8C,CAAC,GACvB;AACxB,QAAM,SAAS,QAAQ,QAAQ,MAAM,OAAO,UAAU,QAAQ,KAAK,IAAI;AACvE,MAAI,OAAQ,MAAK,gBAAgB,OAAO,MAAM,KAAK,OAAO,EAAE,GAAG;AAE/D,OAAK,wBAAwB;AAC7B,QAAM,UAAU,MAAM,OAAO,IAAI,SAAS,EAAE,OAAO,QAAQ,SAAS,GAAG,CAAC,GAAG;AAK3E,QAAM,SAAS,MAAM,OAAO,WAAW;AACvC,QAAM,SAAS,CAAC,OAAe,OAAO,KAAK,CAAC,UAAU,MAAM,OAAO,EAAE;AAErE,QAAM,WAAW,SACb,OAAO,OAAO,CAAC,SAAS,KAAK,WAAW,OAAO,MAAM,KAAK,WAAW,OAAO,EAAE,IAC9E;AACJ,OAAK,cAAc,SAAS,MAAM,OAAO,OAAO,MAAM,iBAAiB;AAEvE,QAAM,YAA2B,CAAC;AAClC,aAAW,QAAQ,UAAU;AAG3B,UAAM,CAAC,SAAS,MAAM,QAAQ,IAAI,MAAM,QAAQ,IAAI;AAAA,MAClD,OAAO,QAAQ,EAAE,SAAS,KAAK,IAAI,CAAC;AAAA,MACpC,OAAO,QAAQ,EAAE,SAAS,KAAK,IAAI,CAAC;AAAA,MACpC,OAAO,iBAAiB,EAAE,SAAS,KAAK,IAAI,CAAC;AAAA,IAC/C,CAAC;AACD,QAAI,CAAC,WAAW,CAAC,KAAM;AAEvB,UAAM,KAAK,OAAO,KAAK,MAAM;AAC7B,UAAM,KAAK,OAAO,KAAK,MAAM;AAC7B,cAAU,KAAK;AAAA,MACb,SAAS,KAAK;AAAA,MACd,QAAQ,EAAE,IAAI,KAAK,QAAQ,QAAQ,IAAI,UAAU,KAAK,UAAU,IAAI,YAAY,EAAE;AAAA,MAClF,QAAQ,EAAE,IAAI,KAAK,QAAQ,QAAQ,IAAI,UAAU,KAAK,UAAU,IAAI,YAAY,EAAE;AAAA,MAClF,KAAK,QAAQ;AAAA,MACb,aAAa,KAAK;AAAA,MAClB,MAAM,KAAK;AAAA,MACX,WAAW,KAAK;AAAA,MAChB,WAAW,SAAS,aAAa,KAAK,YAAY;AAAA,MAClD,GAAI,SAAS,YACT,KAAK,YAAY,KACf,CAAC,IACD,EAAE,QAAQ,eAAe,IAC3B,EAAE,QAAQ,2BAA2B;AAAA,IAC3C,CAAC;AAAA,EACH;AACA,SAAO;AACT;AAOA,eAAsB,KAAK,MAA+B;AACxD,QAAM,OAAO;AAAA,IACX;AAAA,MACE,OAAO,EAAE,MAAM,SAAS;AAAA,MACxB,WAAW,EAAE,MAAM,UAAU;AAAA,MAC7B,MAAM,EAAE,MAAM,SAAS;AAAA,MACvB,OAAO,EAAE,MAAM,SAAS;AAAA,IAC1B;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAEA,QAAM,IAAI,YAAY;AACpB,UAAM,EAAE,QAAQ,QAAQ,IAAI,MAAM,YAAY,EAAE,SAAS,KAAK,QAA8B,CAAC;AAC7F,SAAK,cAAc,OAAO,EAAE;AAE5B,UAAM,QAAQ,MAAM,cAAc,QAAQ;AAAA,MACxC,GAAI,KAAK,QAAQ,EAAE,OAAO,KAAK,MAAgB,IAAI,CAAC;AAAA,MACpD,GAAI,KAAK,QAAQ,EAAE,OAAO,OAAO,KAAK,KAAK,EAAE,IAAI,CAAC;AAAA,IACpD,CAAC;AACD,UAAM,SACJ,KAAK,SAAS,QACV,CAAC,GAAG,KAAK,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,IACvC,CAAC,GAAG,KAAK,EAAE,KAAK,CAAC,GAAG,MAAO,EAAE,YAAY,EAAE,YAAY,IAAI,EAAE,YAAY,EAAE,YAAY,KAAK,CAAE;AAEpG,QAAI;AACJ,QAAI,KAAK,WAAW;AAClB,WAAK,6DAA6D;AAClE,YAAM,OAAO,MAAM,aAAa,QAAQ,MAAM;AAC9C,eAAS,KAAK;AAGd,UAAI,KAAK,WAAW;AAClB;AAAA,UACE,GAAG,KAAK,SAAS;AAAA,QACnB;AAAA,MACF;AAAA,IACF;AAEA;AAAA,MACE;AAAA,QACE;AAAA,QACA,OAAO,OAAO,IAAI,CAAC,UAAU;AAAA,UAC3B,GAAG;AAAA,UACH,GAAI,SAAS,EAAE,OAAO,OAAO,IAAI,KAAK,OAAO,KAAK,KAAK,IAAI,CAAC;AAAA,QAC9D,EAAE;AAAA,MACJ;AAAA,MACA,CAAC,SAAS;AACR,YAAI,CAAC,KAAK,MAAM,QAAQ;AAGtB,kBAAQ;AAAA,YACN,KAAK,QACD;AAAA,gBAAmB,KAAK,KAAe,OAAO,KAAK,OAAO,sCAC1D;AAAA,cAAiB,KAAK,OAAO;AAAA,UACnC;AACA;AAAA,QACF;AACA,cAAM,UAAU,CAAC,QAAQ,OAAO,WAAW,QAAQ,aAAa,UAAU,UAAU;AACpF,cAAM,QAAiC,CAAC,QAAQ,SAAS,SAAS,SAAS,SAAS,QAAQ,MAAM;AAClG,YAAI,QAAQ;AAGV,kBAAQ,OAAO,GAAG,GAAG,aAAa,gBAAgB,OAAO;AACzD,gBAAM,OAAO,GAAG,GAAG,SAAS,SAAS,OAAO;AAAA,QAC9C;AACA;AAAA,UACE;AAAA,UACA,KAAK,MAAM,IAAI,CAAC,SAAS;AACvB,kBAAM,MAAM;AAAA,cACV,GAAG,KAAK,OAAO,MAAM,IAAI,KAAK,OAAO,MAAM;AAAA,cAC3C,UAAU,KAAK,GAAG;AAAA,cAClB,OAAO,KAAK,WAAW;AAAA,cACvB,OAAO,KAAK,IAAI;AAAA;AAAA;AAAA,cAGhB,KAAK,UAAU,SAAS;AAAA;AAAA;AAAA,cAGxB,KAAK,SAAS,OAAO,KAAK,MAAM,IAAI,MAAM,WAAW;AAAA,cACrD,KAAK;AAAA,YACP;AACA,gBAAI,QAAQ;AACV,oBAAM,QAAQ,OAAO,IAAI,KAAK,OAAO;AAIrC,oBAAM,QAAQ,QACV;AAAA,gBACE,GAAI,MAAM,aAAa,CAAC,GAAG,MAAM,UAAU,MAAM,IAAI,CAAC;AAAA,gBACtD,GAAI,MAAM,eAAe,CAAC,GAAG,MAAM,YAAY,WAAW,IAAI,CAAC;AAAA,cACjE,IACA,CAAC;AACL,kBAAI;AAAA,gBACF;AAAA,gBACA;AAAA,gBACA,QAAQ,GAAG,MAAM,SAAS,GAAG,MAAM,SAAS,KAAK,MAAM,KAAK,IAAI,CAAC,MAAM,EAAE,KAAK;AAAA,gBAC9E,SAAS,MAAM,YAAY,KAAK,MAAM,UAAU,SAAS,IAAI;AAAA,gBAC7D,OAAO,YAAY,OAAO,WAAM,IAAI,MAAM,WAAW,KAAK,QAAQ,CAAC,CAAC;AAAA,cACtE;AAAA,YACF;AACA,mBAAO;AAAA,UACT,CAAC;AAAA,UACD;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,EACF,CAAC;AACH;","names":[]}

package/dist/positions-MILT3BRU.js

@@ -0,0 +1,134 @@
+import {
+  done,
+  flags,
+  output,
+  run,
+  step,
+  table,
+  warn
+} from "./chunk-IBVZHLUT.js";
+import {
+  dim,
+  green,
+  red,
+  yellow
+} from "./chunk-IHYFMX5A.js";
+import {
+  formatAmount,
+  loadSession
+} from "./chunk-2OT6LZPW.js";
+
+// src/commands/positions.ts
+var USAGE = `shield-swap positions \u2014 owned liquidity positions and what they are owed
+
+  --network <testnet|mainnet>   default testnet
+  --pool <poolKey>              only positions in this pool
+  --all                         include positions with no entry in the positions
+                                mapping \u2014 a mint still finalizing, or one already
+                                burned whose record the scanner still serves
+  --json                        machine-readable output`;
+async function main(argv) {
+  const args = flags({ pool: { type: "string" }, all: { type: "boolean" } }, USAGE, argv);
+  await run(async () => {
+    const { client, network } = await loadSession({ network: args.network });
+    done(`session on ${network}`);
+    step(
+      args.all ? "scanning unspent and spent position records, then joining chain state" : "scanning position records and joining chain state"
+    );
+    const owned = await client.getOwnedPositions({
+      ...args.pool ? { poolKey: args.pool } : {},
+      // The spent scan is what proves a burn, so it is only worth its cost when
+      // closed positions are going to be shown.
+      ...args.all ? { includeClosed: true } : {}
+    });
+    const tokens = await client.listTokens();
+    const infoOf = (id) => tokens.find((token) => token.id === id);
+    const all = owned.map((position) => {
+      const t0 = infoOf(position.token0Id);
+      const t1 = infoOf(position.token1Id);
+      return {
+        positionTokenId: position.positionTokenId,
+        poolKey: position.poolKey,
+        pair: `${t0?.symbol ?? "?"}/${t1?.symbol ?? "?"}`,
+        decimals0: t0?.decimals ?? 0,
+        decimals1: t1?.decimals ?? 0,
+        tickLower: position.tickLower,
+        tickUpper: position.tickUpper,
+        frozen: position.frozen,
+        // A null state means the positions mapping has no entry, which happens at
+        // both ends of a position's life: a mint that has not finalized, or one
+        // already burned whose record the scanner is still serving. The two are
+        // indistinguishable from here, so the label must not claim either.
+        noChainEntry: position.state === null,
+        // Proven from records, not inferred from the mapping's silence: the burn
+        // consumed the last PositionNFT and re-issued nothing.
+        closed: position.closed,
+        // Left null rather than defaulted to zero. Everything above comes off the
+        // record; these five come only from the positions mapping, and a zero here
+        // would read as a drained position instead of one with nothing to read.
+        state: position.state ? {
+          liquidity: position.state.liquidity,
+          amount0: position.state.amount0,
+          amount1: position.state.amount1,
+          collectable0: position.state.uncollectedFees0,
+          collectable1: position.state.uncollectedFees1
+        } : null
+      };
+    });
+    const hidden = args.all ? 0 : all.filter((row) => row.noChainEntry).length;
+    const rows = args.all ? all : all.filter((row) => !row.noChainEntry);
+    const closed = all.filter((row) => row.closed).length;
+    output({ network, positions: rows, hidden, closed }, (data) => {
+      if (!data.positions.length) {
+        console.log(
+          data.hidden ? `
+No operable positions. ${data.hidden} record(s) have no entry in the positions mapping \u2014 pass --all to list them.` : "\nNo positions. Open one with `shield-swap mint --help`."
+        );
+        return;
+      }
+      table(
+        ["PAIR", "RANGE", "LIQUIDITY", "BACKING", "COLLECTABLE", "STATE", "POSITION ID"],
+        data.positions.map((row) => [
+          row.pair,
+          `${row.tickLower}\u2026${row.tickUpper}`,
+          // An em dash, not a zero: with no mapping entry there is no figure to
+          // report, and printing 0 would be indistinguishable from a drained
+          // position that still has one.
+          row.state ? row.state.liquidity.toString() : dim("\u2014"),
+          // Both sides in one cell, in the pool's own token order: a position is
+          // backed by a pair, and splitting them into four columns of bare numbers
+          // loses which token each belongs to.
+          row.state ? `${formatAmount(row.state.amount0, row.decimals0)} / ${formatAmount(row.state.amount1, row.decimals1)}` : dim("\u2014"),
+          row.state ? `${formatAmount(row.state.collectable0, row.decimals0)} / ${formatAmount(row.state.collectable1, row.decimals1)}` : dim("\u2014"),
+          // `closed` is proven, so it wins over the mapping's silence. Only a
+          // record that is still unspent AND has no entry is genuinely undecided:
+          // a mint mid-finalize, or a burn the scanner has not caught up with.
+          row.closed ? dim("closed") : [row.frozen ? red("FROZEN") : "", row.noChainEntry ? yellow("pending") : ""].filter(Boolean).join(", ") || green("open"),
+          row.positionTokenId
+        ]),
+        ["left", "right", "right", "right", "right", "left", "left"]
+      );
+      const owed = data.positions.filter(
+        (row) => (row.state?.collectable0 ?? 0n) > 0n || (row.state?.collectable1 ?? 0n) > 0n
+      );
+      if (owed.length) {
+        console.log(`
+${owed.length} position(s) have something to collect \u2014 run \`shield-swap collect\`.`);
+      }
+      if (data.positions.some((row) => row.frozen)) {
+        warn("a frozen position blocks every liquidity operation until an admin unfreezes it");
+      }
+      if (data.closed) console.log(`${data.closed} closed position(s) listed \u2014 burned, nothing left to operate on.`);
+      const pending = data.positions.filter((row) => row.noChainEntry && !row.closed).length;
+      if (pending || data.hidden) {
+        warn(
+          `${pending || data.hidden} position(s) hold an unspent record with no entry in the positions mapping \u2014 a mint still finalizing, or a burn the record scanner has not caught up with (it can serve a burned record for minutes). Neither can be operated on` + (data.hidden ? ", and they are not listed above \u2014 pass --all to see them." : ".")
+        );
+      }
+    });
+  });
+}
+export {
+  main
+};
+//# sourceMappingURL=positions-MILT3BRU.js.map

package/dist/positions-MILT3BRU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commands/positions.ts"],"sourcesContent":["/**\n * Position discovery — every liquidity position the account holds, summarized.\n *\n * Discovered from the account's own records, not from a local list: each\n * position is a private NFT, and `getOwnedPositions` joins it with chain state\n * to report the range, the tokens currently backing it, and what `collect`\n * would pay right now.\n *\n * Only positions with an entry in the positions mapping are listed by default —\n * those are the ones that can be increased, decreased, collected from, or burned.\n * A record whose mapping entry is gone holds nothing and cannot be operated on;\n * `--all` lists those too, which is what to reach for when a mint seems missing.\n *\n * Reads only. Spends nothing.\n *\n * Usage:\n *   shield-swap positions                      # testnet, operable positions\n *   shield-swap positions --all                # include ones with no chain entry\n *   shield-swap positions --network mainnet\n *   shield-swap positions --pool <poolKey>     # one pool\n *   shield-swap positions --json\n */\nimport { loadSession, formatAmount } from '../session.js'\nimport { flags, step, done, warn, output, run, table } from '../shared.js'\nimport { dim, green, red, yellow } from '../color.js'\n\nconst USAGE = `shield-swap positions — owned liquidity positions and what they are owed\n\n  --network <testnet|mainnet>   default testnet\n  --pool <poolKey>              only positions in this pool\n  --all                         include positions with no entry in the positions\n                                mapping — a mint still finalizing, or one already\n                                burned whose record the scanner still serves\n  --json                        machine-readable output`\n\n/**\n * Runs the `positions` subcommand.\n *\n * @param argv Arguments after the subcommand name, as the dispatcher supplies them.\n */\nexport async function main(argv: string[]): Promise<void> {\n  const args = flags({ pool: { type: 'string' }, all: { type: 'boolean' } }, USAGE, argv)\n\n  await run(async () => {\n    const { client, network } = await loadSession({ network: args.network as string | undefined })\n    done(`session on ${network}`)\n\n    step(\n      args.all\n        ? 'scanning unspent and spent position records, then joining chain state'\n        : 'scanning position records and joining chain state',\n    )\n    const owned = await client.getOwnedPositions({\n      ...(args.pool ? { poolKey: args.pool as string } : {}),\n      // The spent scan is what proves a burn, so it is only worth its cost when\n      // closed positions are going to be shown.\n      ...(args.all ? { includeClosed: true } : {}),\n    })\n    const tokens = await client.listTokens()\n    const infoOf = (id: string) => tokens.find((token) => token.id === id)\n\n    const all = owned.map((position) => {\n      const t0 = infoOf(position.token0Id)\n      const t1 = infoOf(position.token1Id)\n      return {\n        positionTokenId: position.positionTokenId,\n        poolKey: position.poolKey,\n        pair: `${t0?.symbol ?? '?'}/${t1?.symbol ?? '?'}`,\n        decimals0: t0?.decimals ?? 0,\n        decimals1: t1?.decimals ?? 0,\n        tickLower: position.tickLower,\n        tickUpper: position.tickUpper,\n        frozen: position.frozen,\n        // A null state means the positions mapping has no entry, which happens at\n        // both ends of a position's life: a mint that has not finalized, or one\n        // already burned whose record the scanner is still serving. The two are\n        // indistinguishable from here, so the label must not claim either.\n        noChainEntry: position.state === null,\n        // Proven from records, not inferred from the mapping's silence: the burn\n        // consumed the last PositionNFT and re-issued nothing.\n        closed: position.closed,\n        // Left null rather than defaulted to zero. Everything above comes off the\n        // record; these five come only from the positions mapping, and a zero here\n        // would read as a drained position instead of one with nothing to read.\n        state: position.state\n          ? {\n              liquidity: position.state.liquidity,\n              amount0: position.state.amount0,\n              amount1: position.state.amount1,\n              collectable0: position.state.uncollectedFees0,\n              collectable1: position.state.uncollectedFees1,\n            }\n          : null,\n      }\n    })\n\n    // Hidden rather than dropped: the count is reported below so a position that\n    // exists but cannot be operated on never reads as one the account never had.\n    const hidden = args.all ? 0 : all.filter((row) => row.noChainEntry).length\n    const rows = args.all ? all : all.filter((row) => !row.noChainEntry)\n    const closed = all.filter((row) => row.closed).length\n\n    output({ network, positions: rows, hidden, closed }, (data) => {\n      if (!data.positions.length) {\n        console.log(\n          data.hidden\n            ? `\\nNo operable positions. ${data.hidden} record(s) have no entry in the positions ` +\n                'mapping — pass --all to list them.'\n            : '\\nNo positions. Open one with `shield-swap mint --help`.',\n        )\n        return\n      }\n      table(\n        ['PAIR', 'RANGE', 'LIQUIDITY', 'BACKING', 'COLLECTABLE', 'STATE', 'POSITION ID'],\n        data.positions.map((row) => [\n          row.pair,\n          `${row.tickLower}…${row.tickUpper}`,\n          // An em dash, not a zero: with no mapping entry there is no figure to\n          // report, and printing 0 would be indistinguishable from a drained\n          // position that still has one.\n          row.state ? row.state.liquidity.toString() : dim('—'),\n          // Both sides in one cell, in the pool's own token order: a position is\n          // backed by a pair, and splitting them into four columns of bare numbers\n          // loses which token each belongs to.\n          row.state\n            ? `${formatAmount(row.state.amount0, row.decimals0)} / ${formatAmount(row.state.amount1, row.decimals1)}`\n            : dim('—'),\n          row.state\n            ? `${formatAmount(row.state.collectable0, row.decimals0)} / ${formatAmount(row.state.collectable1, row.decimals1)}`\n            : dim('—'),\n          // `closed` is proven, so it wins over the mapping's silence. Only a\n          // record that is still unspent AND has no entry is genuinely undecided:\n          // a mint mid-finalize, or a burn the scanner has not caught up with.\n          row.closed\n            ? dim('closed')\n            : [row.frozen ? red('FROZEN') : '', row.noChainEntry ? yellow('pending') : '']\n                .filter(Boolean)\n                .join(', ') || green('open'),\n          row.positionTokenId,\n        ]),\n        ['left', 'right', 'right', 'right', 'right', 'left', 'left'],\n      )\n      const owed = data.positions.filter(\n        (row) => (row.state?.collectable0 ?? 0n) > 0n || (row.state?.collectable1 ?? 0n) > 0n,\n      )\n      if (owed.length) {\n        console.log(`\\n${owed.length} position(s) have something to collect — run \\`shield-swap collect\\`.`)\n      }\n      if (data.positions.some((row) => row.frozen)) {\n        warn('a frozen position blocks every liquidity operation until an admin unfreezes it')\n      }\n      if (data.closed) console.log(`${data.closed} closed position(s) listed — burned, nothing left to operate on.`)\n      // Only the undecided ones need the caveat now that burns are proven from\n      // records: an unspent record with no mapping entry is a mint mid-finalize, or\n      // a burn whose record the scanner has not marked spent yet.\n      const pending = data.positions.filter((row) => row.noChainEntry && !row.closed).length\n      if (pending || data.hidden) {\n        warn(\n          `${pending || data.hidden} position(s) hold an unspent record with no entry in the ` +\n            'positions mapping — a mint still finalizing, or a burn the record scanner has not ' +\n            'caught up with (it can serve a burned record for minutes). Neither can be operated on' +\n            (data.hidden ? ', and they are not listed above — pass --all to see them.' : '.'),\n        )\n      }\n    })\n  })\n}\n"],"mappings":"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","names":[]}

package/dist/session.d.ts

@@ -0,0 +1,161 @@
+import * as _provablehq_veil_aleo_sdk from '@provablehq/veil-aleo-sdk';
+import * as _provablehq_veil_core from '@provablehq/veil-core';
+import * as _provablehq_shield_swap_sdk from '@provablehq/shield-swap-sdk';
+
+/** The networks these scripts run against. */
+type Network = 'testnet' | 'mainnet';
+/**
+ * Resolves the network from an explicit choice, the environment, or the default.
+ *
+ * Testnet is the default and mainnet is never reached by omission: a script has
+ * to be told, because everything downstream — the DEX API host, the prover, the
+ * scanner, the token registry, and the identity store — is per-network, and the
+ * mainnet ones move real value.
+ *
+ * @param explicit A `--network` value, when a script parsed one.
+ * @throws When the value is neither network, rather than silently using testnet.
+ */
+declare function resolveNetwork(explicit?: string): Network;
+declare const NETWORK_URL = "https://api.provable.com/v2";
+/** Everything that must survive between agent sessions. */
+type ShieldSwapState = {
+    network: string;
+    /**
+     * DEX API origin this session targets. Unset means the SDK's default
+     * hosted deployment. Set by `shield-swap setup` (`--api-url` / SHIELD_SWAP_API_URL);
+     * the access grant, API token, and airdrop job are scoped to one
+     * deployment, so setup clears them when this changes.
+     */
+    apiUrl?: string;
+    privateKey?: string;
+    address?: string;
+    dexApiToken?: string;
+    accessRedeemed?: boolean;
+    /** Faucet job already requested for this account — prevents double-drawing on re-runs. */
+    airdropJobId?: string;
+};
+/** Per-network state directory. Nothing is shared between networks. */
+declare function stateDir(network: Network): string;
+/**
+ * Where the blinded identity store lives for a network.
+ *
+ * Scoped by network because a reservation is only meaningful against the chain
+ * it was checked on: counters reserved against testnet's
+ * `used_blinded_addresses` say nothing about mainnet's, and one shared file
+ * would hand out identities the other chain has already consumed.
+ */
+declare function blindedStorePath(network: Network): string;
+/**
+ * Where Provable API credentials live for a network.
+ *
+ * Separate from the state file because the SDK owns the format: `shield-swap setup`
+ * hands `fileCredentialStore` this path and the client reads and writes it
+ * directly, including registering a consumer when the file is absent.
+ */
+declare function credentialsPath(network: Network): string;
+/**
+ * Reads a network's state file, or returns a fresh empty state.
+ *
+ * Falls back to the pre-network layout for testnet only, so an existing
+ * `.shield-swap/state.json` keeps working; the next save writes it to the
+ * network-scoped path.
+ */
+declare function loadState(network: Network): ShieldSwapState;
+/**
+ * Writes the state file atomically (temp file + rename, 0600 — it holds the
+ * private key). A crash mid-write can never truncate the only copy of the
+ * key and the open swap handles.
+ */
+declare function saveState(state: ShieldSwapState): void;
+/**
+ * Renders a raw base-unit amount in human units ("0.0534 ETH"), the ONLY
+ * format that should ever reach the user. Raw units (wei-style integers)
+ * are SDK-facing; showing them to a person misstates their balances by
+ * orders of magnitude.
+ */
+declare function formatAmount(amount: bigint, decimals: number, symbol?: string): string;
+/** What {@link namedAmounts} needs of a pool's token to place an amount. */
+type AmountToken = {
+    id: string;
+    symbol: string;
+    decimals: number;
+};
+/**
+ * Places caller-named amounts into a pool's own token order.
+ *
+ * A pool orders its tokens by id, not by anything a caller types, so `--amount0`
+ * is unknowable without reading the pool first: naming a pair `USDCx:ETH` does
+ * not make USDCx side 0. `--amount USDCx:0.5` names the token instead and is
+ * matched here, while `--amount0`/`--amount1` stay available for callers who know
+ * the order. Parsing is the inverse of {@link formatAmount}: human decimals in,
+ * raw base units out. Pure and local.
+ *
+ * @param params.entries `--amount` values, each `<symbol|id>:<decimal>`.
+ * @param params.indexed The raw `--amount0` and `--amount1` strings, in that
+ *   order, `undefined` where the flag was absent.
+ * @param params.tokens The pool's tokens in ITS order — `[token0, token1]`.
+ * @returns Raw base units per side, `undefined` where nothing named that side.
+ * @throws When an entry is malformed, names a token outside the pair, or names a
+ *   side twice — including once by symbol and once by index, where preferring
+ *   either would commit an amount the caller did not ask for.
+ *
+ * @example
+ * const { amount0, amount1 } = namedAmounts({
+ *   entries: ['USDCx:0.5'],
+ *   indexed: [undefined, undefined],
+ *   tokens: [token0, token1],
+ * })
+ */
+declare function namedAmounts(params: {
+    entries: string[];
+    indexed: readonly [string | undefined, string | undefined];
+    tokens: readonly [AmountToken, AmountToken];
+}): {
+    amount0: bigint | undefined;
+    amount1: bigint | undefined;
+};
+/**
+ * Builds the fully wired, authenticated session from the state file.
+ *
+ * Requires `shield-swap setup` to have run (key material in the state file).
+ * Authenticates with the DEX API on every call — the session JWT covers
+ * everything including access/token management, and auto-renews on expiry.
+ *
+ * Provable API credentials are not required up front: the client registers a
+ * consumer through the credential file on first prove or scan when it holds
+ * none — though `shield-swap setup` registers and verifies eagerly, so a session built
+ * after setup has working credentials rather than untested ones.
+ */
+declare function loadSession(options?: {
+    network?: string;
+}): Promise<{
+    client: _provablehq_veil_core.Client<_provablehq_shield_swap_sdk.ShieldSwapActions & _provablehq_veil_core.WalletActions & {
+        recordProvider: _provablehq_veil_core.RecordProvider | undefined;
+    } & _provablehq_veil_aleo_sdk.ProvableApiActions>;
+    account: _provablehq_veil_core.LocalAccount<"privateKey">;
+    scanner: _provablehq_veil_core.RecordProvider & {
+        setSession: (session: _provablehq_veil_aleo_sdk.ProvableSession) => void;
+    };
+    state: ShieldSwapState;
+    aleo: _provablehq_veil_aleo_sdk.AleoSdk;
+    network: Network;
+    blindedIdentities: _provablehq_shield_swap_sdk.BlindedIdentityStore;
+}>;
+/** Polls a predicate until it returns true or attempts run out. */
+declare function pollUntil(fn: () => Promise<boolean>, attempts: number, intervalMs: number): Promise<boolean>;
+/**
+ * Resolves key material and stores it. Priority: existing state → imported
+ * key (`importKey`) → fresh generation, but only when `allowGenerate` is
+ * true. Returning users keep their account; a fresh key is never created
+ * silently.
+ */
+declare function ensureKeyMaterial(state: ShieldSwapState, options?: {
+    importKey?: string;
+    allowGenerate?: boolean;
+}): Promise<ShieldSwapState>;
+/** Signals that setup must ask the user about existing config before creating anything. */
+declare class NeedsConfigDecisionError extends Error {
+    constructor();
+}
+
+export { type AmountToken, NETWORK_URL, NeedsConfigDecisionError, type Network, type ShieldSwapState, blindedStorePath, credentialsPath, ensureKeyMaterial, formatAmount, loadSession, loadState, namedAmounts, pollUntil, resolveNetwork, saveState, stateDir };

package/dist/session.js

@@ -0,0 +1,31 @@
+import {
+  NETWORK_URL,
+  NeedsConfigDecisionError,
+  blindedStorePath,
+  credentialsPath,
+  ensureKeyMaterial,
+  formatAmount,
+  loadSession,
+  loadState,
+  namedAmounts,
+  pollUntil,
+  resolveNetwork,
+  saveState,
+  stateDir
+} from "./chunk-2OT6LZPW.js";
+export {
+  NETWORK_URL,
+  NeedsConfigDecisionError,
+  blindedStorePath,
+  credentialsPath,
+  ensureKeyMaterial,
+  formatAmount,
+  loadSession,
+  loadState,
+  namedAmounts,
+  pollUntil,
+  resolveNetwork,
+  saveState,
+  stateDir
+};
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}