docs(withdraw-cli): scrub internal references from README + comments

Removes internal-only references from the public withdraw-cli release:
private module cross-references in source comments, internal audit-round
tags (R48 / R49 / R55, one in a user-facing console line), and predecessor
build-version comparisons (V9.x / V10). Rewritten to describe the
invariants and the V1 contract surface directly.

Documentation and comments only; no behaviour change.

Author: optivaults-fi

withdraw-cli/README.md

@@ -4,14 +4,14 @@ V1 command-line self-serve withdrawal + Layer 3 dead-man-switch trigger. Runs en
 
 Currently supports **Preprod** (V1 launch-candidate ceremony). Mainnet placeholder ships unfilled — pass `--config <path>` once V1 mainnet ceremony lands.
 
-## What V1 adds vs the V9.x / V10 `withdraw-cli`
+## V1 contract surface
 
-V1 ships a different on-chain contract surface from V9.x / V10:
+This CLI targets the V1 on-chain contract surface:
 
-- **29-field VaultDatum** (vs 25 in V9). Adds `liqwid_positions`, `non_deposit_value`, `last_realloc_time`, `last_fee_update_time`, `last_ada_swap_time`, `keeper_fee_bps`, `gov_fee_bps`, `max_slippage_bps`, `min_swap_peg_bps`, and the new operational flag `community_sunset_triggered`.
-- **R55 compile-time vault NFT anchor**: `vault_nft_policy` is no longer a datum field — it's baked into `vault_proxy` / `vusdcx` / `order` at compile time. The CLI locates the vault UTXO by NFT scan at the proxy address.
-- **Withdraw redeemer signature**: `Constr(1, [shares, receiver, receiver_output_idx])` (V9 was `Constr(1, [shares, receiver])`). The third field defends against R48 M-1 anti-double-satisfaction.
-- **Withdraw-Zero routes through `vault_user`** (V9 used `vault_core`; V1 split the user-flow validators).
+- **29-field VaultDatum**, including `liqwid_positions`, `non_deposit_value`, `last_realloc_time`, `last_fee_update_time`, `last_ada_swap_time`, `keeper_fee_bps`, `gov_fee_bps`, `max_slippage_bps`, `min_swap_peg_bps`, and the operational flag `community_sunset_triggered`.
+- **Compile-time vault NFT anchor**: `vault_nft_policy` is not a datum field — it's baked into `vault_proxy` / `vusdcx` / `order` at compile time. The CLI locates the vault UTXO by NFT scan at the proxy address.
+- **Withdraw redeemer signature**: `Constr(1, [shares, receiver, receiver_output_idx])`. The third field pins which output index the receiver payout must land at, closing an output double-satisfaction gap.
+- **Withdraw-Zero routes through `vault_user`**: the user-flow validators are split, so Withdraw touches `vault_user` only.
 - **Layer 3 CommunitySunset**: a permissionless redeemer any vUSDCx holder can call after ≥90 days of operational inactivity. Sets `frozen=1 + community_sunset_triggered=1`, opening the permissionless `vault_recall.RecallFromLiqwid` + `vault_protocol.DeployToProtocol` Layer 2 paths. The CLI exposes this as `sunset-status` (read) + `sunset-trigger` (write).
 
 ## Quick start
@@ -49,7 +49,7 @@ optivaults-v1-withdraw balance \
 
 ### `quote` — estimate output
 
-Pure-math preview of a Withdraw, including R49 M-4 deferred-yield (subtract NET not BASE from `total_deposited`) and the 7-day keeper-inactive fee waiver.
+Pure-math preview of a Withdraw, including deferred-yield accounting (subtract NET not BASE from `total_deposited`) and the 7-day keeper-inactive fee waiver.
 
 ```bash
 optivaults-v1-withdraw quote \
@@ -126,7 +126,7 @@ The CLI builds V1 transactions with:
 - **Proxy spend** — vault UTXO at proxy address with `ProxyRedeemer::UseUser = Constr(0,[])`
 - **User staking withdrawal** — `withdraw(user_reward_addr, 0, Constr(1, [shares, receiver, receiver_output_idx]))`
 - **vUSDCx burn** — `mintAssets({vusdcx: -shares}, Constr(1, []))`
-- **Reference scripts** — `readFrom([vaultProxy, vaultUser, vusdcx])` (3 entries, identical to V9.x — the additional V1 staking validators are not needed for Withdraw)
+- **Reference scripts** — `readFrom([vaultProxy, vaultUser, vusdcx])` (3 entries — the additional V1 staking validators are not needed for Withdraw)
 
 CommunitySunset replaces the `withdraw` redeemer with `Constr(3, [])` and skips the burn + payout outputs (datum-only mutation, vault assets unchanged).
 

withdraw-cli/src/cli.ts

@@ -188,7 +188,7 @@ program
     const shares = BigInt(opts.shares)
     const q = computeWithdrawQuote(vault, shares)
 
-    console.log('── Withdraw Quote (V1, R49 M-4 deferred-yield) ──')
+    console.log('── Withdraw Quote (V1, deferred-yield accounting) ──')
     console.log(`  Shares to burn:       ${q.shares.toString()}`)
     console.log(`  Gross withdraw:       ${fmtMicro(q.baseWithdraw)} (deposit-token units)`)
     console.log(`  Early fee:            ${fmtMicro(q.earlyFee)} (${q.keeperInactive ? 'WAIVED — keeper inactive 7d+' : 'active'})`)

withdraw-cli/src/config.ts

@@ -75,7 +75,7 @@ export interface V1Config {
 
   /// Bech32 address of the vault UTXO (lives at proxy script address).
   proxyAddr: string
-  /// Hex28 — vault NFT minting policy (R55 compile-time anchor).
+  /// Hex28 — vault NFT minting policy (compile-time anchor).
   vaultNftPolicy: string
   /// Hex — vault NFT asset name (typically "OptiVault" hex).
   vaultNftName: string

withdraw-cli/src/vault.ts

@@ -2,24 +2,23 @@
  * V1 vault state query + Withdraw-Zero TX builder + CommunitySunset
  * (Layer 3 90-day dead-man-switch) TX builder.
  *
- * V1 differs from V9.x / V10:
- *   - 29-field VaultDatum (added: liqwid_positions, non_deposit_value,
+ * V1 contract surface:
+ *   - 29-field VaultDatum (liqwid_positions, non_deposit_value,
  *     last_realloc_time, last_fee_update_time, last_ada_swap_time,
  *     keeper_fee_bps, gov_fee_bps, max_slippage_bps, min_swap_peg_bps,
  *     community_sunset_triggered)
- *   - Withdraw redeemer: Constr(1, [shares, receiver, receiver_output_idx])
- *     (V9 was Constr(1, [shares, receiver]) — 2 fields; V1 added
- *     receiver_output_idx to defend against R48 M-1 anti-double-satisfaction)
- *   - Withdraw routes through `vault_user` staking validator (V9 used
- *     `vault_core`; V1 split user-flow into `vault_user` + `vault_keeper_hot`)
- *   - vault_proxy.UseUser = Constr(0, []) (was UseCore)
- *   - vault_nft_policy is a compile-time anchor (R55), not a datum field;
+ *   - Withdraw redeemer: Constr(1, [shares, receiver, receiver_output_idx]) —
+ *     receiver_output_idx pins the payout output index, defending against
+ *     output double-satisfaction
+ *   - Withdraw routes through the `vault_user` staking validator (the
+ *     user-flow validators are split into `vault_user` + `vault_keeper_hot`)
+ *   - vault_proxy.UseUser = Constr(0, [])
+ *   - vault_nft_policy is a compile-time anchor, not a datum field;
  *     vault is identified via NFT scan at proxy address
  *   - CommunitySunset = Constr(3, []) — permissionless redeemer; sets
  *     frozen=1 + community_sunset_triggered=1 after ≥90d operational inactivity
  *
- * V1 Withdraw TX structure (Withdraw-Zero pattern, identical 3 ref scripts
- * to V9):
+ * V1 Withdraw TX structure (Withdraw-Zero pattern, 3 ref scripts):
  *   - Spend vault UTXO at proxy address with ProxyRedeemer::UseUser
  *   - Withdraw 0 lovelace from `vault_user` reward address with
  *     VaultRedeemer::Withdraw(shares, receiver, receiver_output_idx)
@@ -200,9 +199,6 @@ function hexToUint8Array(hex: string): Uint8Array {
  *      letting Lucid send hex text.
  *   3. Return `{redeemer_tag, redeemer_index, ex_units}` shape that
  *      Lucid's downstream effect-ts switch expects.
- *
- * Mirrors `v1/reference/frontend/src/lib/lucidClient.ts::patchBlockfrostEvaluate`
- * + `deploy/lib/blockfrostProvider.ts::patchEval`.
  */
 function patchBlockfrostEvaluate(bf: any, baseUrl: string, key: string): void {
   bf.evaluateTx = async (tx: string, _additionalUTxOs?: unknown) => {
@@ -264,7 +260,7 @@ function patchBlockfrostEvaluate(bf: any, baseUrl: string, key: string): void {
  * missing `drep_deposit` / `gov_action_deposit` fields). Replace its
  * `getProtocolParameters` with a Conway-safe implementation that reads
  * Blockfrost REST directly + applies fallbacks. Cached per provider
- * instance. Mirrors `v1/keeper/src/agent/utils/blockfrostProtocolParamsPatch.ts`.
+ * instance.
  */
 function patchProtocolParamsConwaySafe(bf: any, url: string, key: string): void {
   let cached: any = null
@@ -353,7 +349,7 @@ export function hydrateRewardAddrs(cfg: V1Config): void {
 
 /**
  * Locate the unique vault UTXO at proxy.address by scanning for the
- * one-shot vault NFT (R55 compile-time anchor). The deploy ceremony
+ * one-shot vault NFT (compile-time anchor). The deploy ceremony
  * mints exactly one such NFT and burns the mint window deadline, so
  * there is provably one vault UTxO per proxy address.
  */
@@ -589,7 +585,7 @@ export async function buildWithdrawTx(
   // Build new datum — copy all 29 fields, mutate only accounting deltas.
   const oldDatum = Data.from(state.rawDatum) as any
   const newFields = [...(oldDatum.fields as unknown[])]
-  newFields[VF.total_deposited] = state.totalDeposited - quote.netWithdraw // R49 M-4 deferred-yield: subtract NET, not BASE
+  newFields[VF.total_deposited] = state.totalDeposited - quote.netWithdraw // deferred-yield: subtract NET, not BASE
   newFields[VF.total_shares] = state.totalShares - shares
   newFields[VF.idle_buffer] = state.idleBuffer - quote.netWithdraw
   const newDatumCbor = Data.to(new Constr(0, newFields as any) as any)