@subly_fi/pay 0.7.2 → 0.8.0

package/README.md

@@ -2,55 +2,59 @@
 
 CLI and stdio MCP client for paying compatible x402 APIs with Kamino USDC vault yield on Solana. MIT licensed. Works with your own [Subly relayer](https://github.com/SublyFi/subly-payment-protocol/tree/main/deploy); no Subly account is required.
 
-Version 0.7 is beta software and has not had an external security audit. Vault operations use real mainnet funds. Yield accounting and owner policies depend on your relayer operator. Read the [security model](https://github.com/SublyFi/subly-payment-protocol/blob/main/docs/security-model.md).
+Version 0.8 is beta software and has not had an external security audit. Vault operations use real mainnet funds. Yield accounting and owner policies depend on your relayer operator. Read the [security model](https://github.com/SublyFi/subly-payment-protocol/blob/main/docs/security-model.md).
 
 ## Quick start
 
 You need **Node.js 24+**, a Solana agent wallet with mainnet USDC, a trusted relayer URL, and a mainnet RPC endpoint that supports transaction simulation with inner instructions. Your wallet can be a local keypair or a supported custody signer. The owner who approves spending controls can use a passkey or a separate Solana wallet.
 
 ```bash
-npx -y @subly_fi/pay@0.7.2 --help
+npx -y @subly_fi/pay@0.8.0 --help
 export SUBLY_RELAYER_URL=https://your-relayer.example.com
 export SOLANA_RPC_URL=https://your-mainnet-rpc.example.com
 export SUBLY_DEMO_AGENT_KEYPAIR_PATH=/absolute/path/to/agent.json
-npx -y @subly_fi/pay@0.7.2 doctor
-npx -y @subly_fi/pay@0.7.2 vaults
+npx -y @subly_fi/pay@0.8.0 doctor
+npx -y @subly_fi/pay@0.8.0 vaults
 ```
 
 Use an existing dedicated agent wallet, or create one with `solana-keygen new -o agent.json`. Keep its recovery material private and restrict the file to its owner (`chmod 600 agent.json`). Fund its public address with **USDC on Solana mainnet**. Subly does not create or fund wallets. Vault fees require a funded relayer sponsor; the final API payment requires the seller's facilitator fee payer.
 
 1. Review the selected vault, its curator, fees and liquidity. For a catalogue supplied by your operator, install the reviewed file locally and set `SUBLY_VAULTS_FILE=/absolute/path/vaults.json`. `SUBLY_VAULT_ADDRESS` selects one listed vault for CLI commands. Never install transaction trust anchors merely because a remote response says to.
-2. Create an owner setup link. This example pre-approves a **1.01 USDC** deposit; the selected vault's minimum can differ:
+2. Create an owner setup link. On the first owner registration, this example pre-approves a **1.01 USDC** deposit; the selected vault's minimum can differ:
 
    ```bash
-   npx -y @subly_fi/pay@0.7.2 setup-link --initial-deposit 1010000
+   npx -y @subly_fi/pay@0.8.0 setup-link --initial-deposit 1010000
    ```
 
-   Open the returned `setupUrl`, review the wallet, vault and limits, then approve with your passkey or wallet. Links expire in 10 minutes. Treat setup and approval links as private capabilities. The first person completing an initial setup becomes the owner for that wallet/vault.
+   Open the returned `setupUrl`, review the wallet, vault and limits, then approve with your passkey or wallet. Links expire in 10 minutes. Treat setup and approval links as private capabilities. The first person completing an initial setup becomes the owner for that wallet/vault. Replacing an existing mandate requires a separate deposit approval; follow the approval link returned by the deposit command.
 3. Check completion and deposit promptly; initial deposit approval lasts about 15 minutes:
 
    ```bash
-   npx -y @subly_fi/pay@0.7.2 setup-status <sessionId>
-   npx -y @subly_fi/pay@0.7.2 deposit 1010000
-   npx -y @subly_fi/pay@0.7.2 budget
+   npx -y @subly_fi/pay@0.8.0 setup-status <sessionId>
+   npx -y @subly_fi/pay@0.8.0 deposit 1010000
+   npx -y @subly_fi/pay@0.8.0 budget
    ```
 
 4. Wait until **spendable yield** covers the price and vault fees. A new deposit does not immediately provide a payment budget. Then request a compatible API:
 
    ```bash
-   npx -y @subly_fi/pay@0.7.2 fetch https://seller.example.com/paid-resource
+   npx -y @subly_fi/pay@0.8.0 fetch https://seller.example.com/paid-resource
    ```
 
 5. Withdraw funds back to the same agent wallet when needed:
 
    ```bash
-   npx -y @subly_fi/pay@0.7.2 withdraw 1000000
+   npx -y @subly_fi/pay@0.8.0 withdraw 1000000
    ```
 
 All amounts are raw USDC integers: `1000000` = 1 USDC. `fetch` defaults to a **0.01 USDC cap**, configurable with `SUBLY_MCP_MAX_AMOUNT_RAW_USDC` or `fetch <URL> <capRawUSDC>`. The owner mandate may set stricter limits. `setup-link --help` lists policy options. A withdrawal can include principal and is subject to liquidity, fees and the owner's policy. A revoked mandate also blocks relayer withdrawals.
 
 A subsequent deposit/payment/withdrawal may return `approvalRequired` with an `approveUrl`. After the owner approves, retry the same operation with the returned `apr_...` as a trailing argument. Never automatically retry a transaction reported as submitted or an API payment with an unknown outcome.
 
+Status lookup requires a **0.8.0 or newer relayer** so it can disable rebroadcast of an unresolved transaction with the authenticated `?resubmit=false` option. Upgrade the relayer before using this command.
+
+For an interrupted deposit or withdrawal, keep its `depositId` (`dep_...`) or `withdrawalId` (`wdr_...`) and run `pay status <intentId>` with the same wallet, selected vault and relayer. This reads and reconciles the original operation; it does not prepare, sign or send another transaction. The result includes the requested/confirmed amount, transaction signature and next action. `submitted` means check the same ID again later. A successful status command exits zero even when the original operation is still pending or failed; inspect its `status` and `nextAction`. Wallet-auth message signing is required, but no client RPC call is needed.
+
 ## MCP configuration
 
 Add this to the MCP configuration of your editor or agent host. Replace all example values with your own absolute paths and endpoints. Pinning the version keeps upgrades explicit.
@@ -60,7 +64,7 @@ Add this to the MCP configuration of your editor or agent host. Replace all exam
   "mcpServers": {
     "subly": {
       "command": "npx",
-      "args": ["-y", "@subly_fi/pay@0.7.2", "mcp"],
+      "args": ["-y", "@subly_fi/pay@0.8.0", "mcp"],
       "env": {
         "SUBLY_RELAYER_URL": "https://your-relayer.example.com",
         "SOLANA_RPC_URL": "https://your-mainnet-rpc.example.com",
@@ -73,7 +77,7 @@ Add this to the MCP configuration of your editor or agent host. Replace all exam
 }
 ```
 
-Tools: `list_subly_vaults`, `select_subly_vault`, `create_subly_setup_link`, `check_subly_setup`, `deposit_to_subly_vault`, `get_subly_yield_budget`, `withdraw_from_subly_vault`, `fetch_with_subly_payment`. Ask the agent to list vaults and follow owner setup before depositing. Each selected vault has its own mandate and accounting; changing selection never moves funds. Stdio stdout is reserved for MCP messages.
+Tools: `list_subly_vaults`, `select_subly_vault`, `create_subly_setup_link`, `check_subly_setup`, `check_subly_vault_operation`, `deposit_to_subly_vault`, `get_subly_yield_budget`, `withdraw_from_subly_vault`, `fetch_with_subly_payment`. Ask the agent to list vaults and follow owner setup before depositing. Each selected vault has its own mandate and accounting; changing selection never moves funds. Stdio stdout is reserved for MCP messages.
 
 ## Configuration
 
@@ -99,8 +103,10 @@ Only sellers offering **Solana mainnet USDC `exact`** with `extra.feePayer` are
 - `doctor` performs read-only configuration, relayer/vault and RPC checks. It never signs or transacts; it does not prove vault safety or available yield.
 - A withdrawal preview failure is a refusal to sign. Check your RPC's simulation support and liquidity; do not disable transaction validation.
 - Preserve the pending-state JSON across restarts and upgrades. An `external_outcome_unknown` record blocks a second payment until you investigate the seller/facilitator outcome.
+- When `fetch` stops while realizing yield, retry the same request with the same wallet, vault, relayer, method, body and headers. A saved withdrawal checkpoint resumes the original withdrawal and reuses its confirmed funds. It never prepares a replacement during recovery, even with `forceNewPayment`. If interruption occurred before the withdrawal ID was saved, or the original withdrawal ended unsuccessfully, reconcile that operation with the operator before starting another payment.
+- Older pending records remain blocked for investigation because they do not identify a resumable withdrawal. Keep the state file; do not downgrade the client while a realization is pending.
 - Concurrent clients using the same state file serialize payments with a `.lock` file. After a crash, stop **all** clients using that file before removing only the stale `.lock`. Preserve the JSON. A new file or another machine cannot coordinate with the old one.
-- `submitted` means the transaction may still confirm. Poll the original intent ID / transaction instead of preparing another deposit or withdrawal.
+- `submitted` means the transaction may still confirm. For a manual deposit or withdrawal, run `pay status <intentId>` or call `check_subly_vault_operation` with `intentId` instead of repeating the operation. Keep the original wallet, selected vault and relayer. An API `fetch` uses the saved recovery checkpoint described above.
 - Setup passkeys bind to the operator's domain. Use the original domain and device credential; follow the documented recovery delay if access is lost.
 
 [Full troubleshooting](https://github.com/SublyFi/subly-payment-protocol/blob/main/docs/troubleshooting.md) · [Support](https://github.com/SublyFi/subly-payment-protocol/blob/main/SUPPORT.md) · [Private security reports](https://github.com/SublyFi/subly-payment-protocol/security/advisories/new)

package/dist/budget.js

@@ -1790,6 +1790,18 @@ async function assertWithdrawalPreview(input) {
   }
 }
 
+// ../../src/lib/canonical-json.ts
+import { createHash as createHash3 } from "node:crypto";
+function canonicalJson2(value) {
+  return stableStringify(value);
+}
+function sha256HexOf(data) {
+  return createHash3("sha256").update(data, "utf8").digest("hex");
+}
+function canonicalJsonHash(value) {
+  return sha256HexOf(canonicalJson2(value));
+}
+
 // ../../src/client/lookup-tables.ts
 import { fetchAllMaybeAddressLookupTable } from "@solana-program/address-lookup-table";
 import { address, getCompiledTransactionMessageDecoder as getCompiledTransactionMessageDecoder2 } from "@solana/kit";
@@ -1831,14 +1843,14 @@ async function fetchLookupTablesForTransaction(rpc, serializedTransaction) {
 }
 
 // ../../src/api/wallet-auth.ts
-import { createHash as createHash3 } from "node:crypto";
+import { createHash as createHash4 } from "node:crypto";
 import bs587 from "bs58";
 import nacl3 from "tweetnacl";
 var WALLET_AUTH_WALLET_HEADER = "x-subly-wallet";
 var WALLET_AUTH_SIGNED_AT_HEADER = "x-subly-signed-at";
 var WALLET_AUTH_SIGNATURE_HEADER = "x-subly-signature";
 function sha256Hex(data) {
-  return createHash3("sha256").update(data, "utf8").digest("hex");
+  return createHash4("sha256").update(data, "utf8").digest("hex");
 }
 function walletAuthMessage(params) {
   return new TextEncoder().encode(
@@ -1882,6 +1894,11 @@ var VaultFlowClientError = class extends Error {
   code;
   errorDetails;
 };
+function vaultOperationKind(intentId) {
+  if (/^dep_[0-9a-f]{32}$/.test(intentId)) return "deposit";
+  if (/^wdr_[0-9a-f]{32}$/.test(intentId)) return "withdrawal";
+  throw new VaultFlowClientError("read", "intentId must be the original dep_ or wdr_ ID followed by 32 lowercase hexadecimal characters");
+}
 var VaultFlowClient = class {
   vault;
   rpc;
@@ -1984,9 +2001,36 @@ var VaultFlowClient = class {
         ...input.approvalId === void 0 ? {} : { approvalId: input.approvalId }
       }
     );
+    this.assertPreparedWithdrawal(prepared, input);
+    await input.onPrepared?.(prepared);
+    return this.submitPreparedWithdrawal(prepared, input);
+  }
+  /** Reconcile or submit the original intent; never prepare a replacement. */
+  async resumeWithdrawal(prepared, input) {
+    this.assertPreparedWithdrawal(prepared, input);
+    const current = await this.getJson(
+      `/v1/withdrawals/${encodeURIComponent(prepared.withdrawalId)}`
+    );
+    if (current.withdrawalId !== prepared.withdrawalId || current.wallet !== this.signer.walletAddress || current.vault !== this.vault.address || current.requestedWithdrawRawUsdc !== input.amountRawUsdc.toString() || current.purpose !== (input.purpose ?? "normal") || canonicalJsonHash(current.paymentBinding ?? null) !== canonicalJsonHash(input.payment ?? null) || current.serializedTransaction !== prepared.serializedTransaction || current.preparedMessageHash !== prepared.signingIntent.preparedMessageHash || current.destinationUsdcAta !== prepared.destinationUsdcAta) {
+      throw new VaultFlowClientError("read", "Saved withdrawal differs from the original operation; refusing to resume");
+    }
+    if (current.status === "prepared") {
+      return this.submitPreparedWithdrawal(prepared, input);
+    }
+    if (!["submitted", "confirmed", "failed", "failed_not_submitted", "expired", "quarantined"].includes(current.status)) {
+      throw new VaultFlowClientError("read", "Relayer returned an unknown withdrawal status");
+    }
+    return this.withdrawalOutcome(prepared, current);
+  }
+  assertPreparedWithdrawal(prepared, input) {
     if (prepared.signingIntent?.wallet !== this.signer.walletAddress || prepared.signingIntent.vault !== this.vault.address || prepared.requestedWithdrawRawUsdc !== input.amountRawUsdc.toString() || prepared.purpose !== (input.purpose ?? "normal") || input.purpose === "yield_realize" && prepared.signingIntent.allowFullExit) {
       throw new VaultFlowClientError("prepare", "Prepared withdrawal differs from the requested operation");
     }
+    if (typeof prepared.withdrawalId !== "string" || prepared.withdrawalId.length === 0) {
+      throw new VaultFlowClientError("prepare", "Prepared withdrawal has no withdrawal ID");
+    }
+  }
+  async submitPreparedWithdrawal(prepared, input) {
     await assertWithdrawalPreview({
       rpc: this.rpc,
       serializedTransaction: prepared.serializedTransaction,
@@ -2000,6 +2044,7 @@ var VaultFlowClient = class {
       serializedTransaction: prepared.serializedTransaction,
       lookupTables: await this.lookupTablesFor(prepared.serializedTransaction)
     });
+    input.onBeforeSubmit?.();
     let outcome = await this.postJson("submit", "/v1/withdrawals/submit", {
       withdrawalId: prepared.withdrawalId,
       serializedTransaction: signed.serializedTransaction,
@@ -2011,6 +2056,9 @@ var VaultFlowClient = class {
         outcome
       );
     }
+    return this.withdrawalOutcome(prepared, outcome);
+  }
+  withdrawalOutcome(prepared, outcome) {
     return {
       withdrawalId: prepared.withdrawalId,
       status: outcome.status,
@@ -2021,6 +2069,40 @@ var VaultFlowClient = class {
       errorCode: outcome.errorCode ?? null
     };
   }
+  /** Authenticated read/reconciliation only: never prepare, sign or submit a transaction. */
+  async getOperationStatus(intentId) {
+    const kind = vaultOperationKind(intentId);
+    const raw = await this.getJson(`/v1/${kind === "deposit" ? "deposits" : "withdrawals"}/${intentId}?resubmit=false`);
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new VaultFlowClientError("read", "Relayer returned an invalid operation status");
+    }
+    const record = raw;
+    if (record[kind === "deposit" ? "depositId" : "withdrawalId"] !== intentId || record.wallet !== this.signer.walletAddress || record.vault !== this.vault.address) {
+      throw new VaultFlowClientError("read", "Operation does not match the requested ID, current wallet or selected vault; use the original wallet, vault and relayer");
+    }
+    const requested = record[kind === "deposit" ? "amountRawUsdc" : "requestedWithdrawRawUsdc"];
+    const actual = record[kind === "deposit" ? "actualDepositRawUsdc" : "actualWithdrawRawUsdc"];
+    if (typeof record.status !== "string" || !["prepared", "submitted", "confirmed", "failed", "expired", "failed_not_submitted"].includes(record.status) || typeof requested !== "string" || !/^\d+$/.test(requested) || actual !== null && (typeof actual !== "string" || !/^\d+$/.test(actual)) || record.txSignature !== null && (typeof record.txSignature !== "string" || record.txSignature.length === 0) || record.errorCode !== null && typeof record.errorCode !== "string" || record.status === "confirmed" && (actual === null || record.txSignature === null)) {
+      throw new VaultFlowClientError("read", "Relayer returned incomplete or invalid operation status fields");
+    }
+    const status = record.status;
+    const nextAction = status === "confirmed" ? "done" : status === "submitted" || status === "prepared" ? "check_again" : "reconcile_with_operator";
+    const message = status === "confirmed" ? `The original ${kind} is confirmed.` : status === "submitted" ? "The original transaction is still confirming. Check this same intent ID again; do not repeat the deposit or withdrawal." : status === "prepared" ? "The original intent is prepared. This status check does not submit it. Check the same ID again or ask the operator to reconcile it before starting another operation." : "The original operation ended without a confirmed result. Reconcile its intent ID and transaction with the operator before starting another operation.";
+    return {
+      intentId,
+      kind,
+      wallet: this.signer.walletAddress,
+      vault: this.vault.address,
+      status,
+      requestedAmountRawUsdc: requested,
+      actualAmountRawUsdc: actual,
+      txSignature: record.txSignature,
+      errorCode: record.errorCode,
+      stillConfirming: status === "submitted",
+      nextAction,
+      message
+    };
+  }
   /**
    * Reads the yield budget. Syncs the relayer's ledger from chain first (so
    * yield accrued since the last sync shows up); the sync is best-effort and

package/dist/cli.js

@@ -6,7 +6,7 @@ const here = dirname(fileURLToPath(import.meta.url));
 const TARGETS = {
   mcp: "mcp-server.js", fetch: "pay.js", deposit: "deposit.js", withdraw: "withdraw.js",
   "setup-link": "setup-link.js", "setup-status": "setup-status.js",
-  doctor: "doctor.js", budget: "budget.js", vaults: "vaults.js"
+  doctor: "doctor.js", budget: "budget.js", vaults: "vaults.js", status: "status.js"
 };
 const HELP = `Subly — x402 payments from Kamino USDC vault yield
 
@@ -18,6 +18,7 @@ Usage: pay <command> [arguments]
   deposit <rawUSDC> [approvalId] Deposit into the selected vault (real funds)
   budget                         Refresh and read the selected vault's yield budget
   withdraw <rawUSDC> [approvalId] Withdraw to the agent wallet (real funds)
+  status <dep_...|wdr_...>        Check the original deposit/withdrawal (no new transaction)
   fetch <URL>                    Pay a compatible x402 API within the configured cap
   mcp                            Start the stdio MCP server
   --version                      Print package version

package/dist/deposit.js

@@ -1886,6 +1886,18 @@ async function assertWithdrawalPreview(input) {
   }
 }
 
+// ../../src/lib/canonical-json.ts
+import { createHash as createHash4 } from "node:crypto";
+function canonicalJson2(value) {
+  return stableStringify(value);
+}
+function sha256HexOf(data) {
+  return createHash4("sha256").update(data, "utf8").digest("hex");
+}
+function canonicalJsonHash(value) {
+  return sha256HexOf(canonicalJson2(value));
+}
+
 // ../../src/client/lookup-tables.ts
 import { fetchAllMaybeAddressLookupTable } from "@solana-program/address-lookup-table";
 import { address, getCompiledTransactionMessageDecoder as getCompiledTransactionMessageDecoder2 } from "@solana/kit";
@@ -1941,6 +1953,11 @@ var VaultFlowClientError = class extends Error {
   code;
   errorDetails;
 };
+function vaultOperationKind(intentId) {
+  if (/^dep_[0-9a-f]{32}$/.test(intentId)) return "deposit";
+  if (/^wdr_[0-9a-f]{32}$/.test(intentId)) return "withdrawal";
+  throw new VaultFlowClientError("read", "intentId must be the original dep_ or wdr_ ID followed by 32 lowercase hexadecimal characters");
+}
 var VaultFlowClient = class {
   vault;
   rpc;
@@ -2043,9 +2060,36 @@ var VaultFlowClient = class {
         ...input.approvalId === void 0 ? {} : { approvalId: input.approvalId }
       }
     );
+    this.assertPreparedWithdrawal(prepared, input);
+    await input.onPrepared?.(prepared);
+    return this.submitPreparedWithdrawal(prepared, input);
+  }
+  /** Reconcile or submit the original intent; never prepare a replacement. */
+  async resumeWithdrawal(prepared, input) {
+    this.assertPreparedWithdrawal(prepared, input);
+    const current = await this.getJson(
+      `/v1/withdrawals/${encodeURIComponent(prepared.withdrawalId)}`
+    );
+    if (current.withdrawalId !== prepared.withdrawalId || current.wallet !== this.signer.walletAddress || current.vault !== this.vault.address || current.requestedWithdrawRawUsdc !== input.amountRawUsdc.toString() || current.purpose !== (input.purpose ?? "normal") || canonicalJsonHash(current.paymentBinding ?? null) !== canonicalJsonHash(input.payment ?? null) || current.serializedTransaction !== prepared.serializedTransaction || current.preparedMessageHash !== prepared.signingIntent.preparedMessageHash || current.destinationUsdcAta !== prepared.destinationUsdcAta) {
+      throw new VaultFlowClientError("read", "Saved withdrawal differs from the original operation; refusing to resume");
+    }
+    if (current.status === "prepared") {
+      return this.submitPreparedWithdrawal(prepared, input);
+    }
+    if (!["submitted", "confirmed", "failed", "failed_not_submitted", "expired", "quarantined"].includes(current.status)) {
+      throw new VaultFlowClientError("read", "Relayer returned an unknown withdrawal status");
+    }
+    return this.withdrawalOutcome(prepared, current);
+  }
+  assertPreparedWithdrawal(prepared, input) {
     if (prepared.signingIntent?.wallet !== this.signer.walletAddress || prepared.signingIntent.vault !== this.vault.address || prepared.requestedWithdrawRawUsdc !== input.amountRawUsdc.toString() || prepared.purpose !== (input.purpose ?? "normal") || input.purpose === "yield_realize" && prepared.signingIntent.allowFullExit) {
       throw new VaultFlowClientError("prepare", "Prepared withdrawal differs from the requested operation");
     }
+    if (typeof prepared.withdrawalId !== "string" || prepared.withdrawalId.length === 0) {
+      throw new VaultFlowClientError("prepare", "Prepared withdrawal has no withdrawal ID");
+    }
+  }
+  async submitPreparedWithdrawal(prepared, input) {
     await assertWithdrawalPreview({
       rpc: this.rpc,
       serializedTransaction: prepared.serializedTransaction,
@@ -2059,6 +2103,7 @@ var VaultFlowClient = class {
       serializedTransaction: prepared.serializedTransaction,
       lookupTables: await this.lookupTablesFor(prepared.serializedTransaction)
     });
+    input.onBeforeSubmit?.();
     let outcome = await this.postJson("submit", "/v1/withdrawals/submit", {
       withdrawalId: prepared.withdrawalId,
       serializedTransaction: signed.serializedTransaction,
@@ -2070,6 +2115,9 @@ var VaultFlowClient = class {
         outcome
       );
     }
+    return this.withdrawalOutcome(prepared, outcome);
+  }
+  withdrawalOutcome(prepared, outcome) {
     return {
       withdrawalId: prepared.withdrawalId,
       status: outcome.status,
@@ -2080,6 +2128,40 @@ var VaultFlowClient = class {
       errorCode: outcome.errorCode ?? null
     };
   }
+  /** Authenticated read/reconciliation only: never prepare, sign or submit a transaction. */
+  async getOperationStatus(intentId) {
+    const kind = vaultOperationKind(intentId);
+    const raw = await this.getJson(`/v1/${kind === "deposit" ? "deposits" : "withdrawals"}/${intentId}?resubmit=false`);
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new VaultFlowClientError("read", "Relayer returned an invalid operation status");
+    }
+    const record = raw;
+    if (record[kind === "deposit" ? "depositId" : "withdrawalId"] !== intentId || record.wallet !== this.signer.walletAddress || record.vault !== this.vault.address) {
+      throw new VaultFlowClientError("read", "Operation does not match the requested ID, current wallet or selected vault; use the original wallet, vault and relayer");
+    }
+    const requested = record[kind === "deposit" ? "amountRawUsdc" : "requestedWithdrawRawUsdc"];
+    const actual = record[kind === "deposit" ? "actualDepositRawUsdc" : "actualWithdrawRawUsdc"];
+    if (typeof record.status !== "string" || !["prepared", "submitted", "confirmed", "failed", "expired", "failed_not_submitted"].includes(record.status) || typeof requested !== "string" || !/^\d+$/.test(requested) || actual !== null && (typeof actual !== "string" || !/^\d+$/.test(actual)) || record.txSignature !== null && (typeof record.txSignature !== "string" || record.txSignature.length === 0) || record.errorCode !== null && typeof record.errorCode !== "string" || record.status === "confirmed" && (actual === null || record.txSignature === null)) {
+      throw new VaultFlowClientError("read", "Relayer returned incomplete or invalid operation status fields");
+    }
+    const status = record.status;
+    const nextAction = status === "confirmed" ? "done" : status === "submitted" || status === "prepared" ? "check_again" : "reconcile_with_operator";
+    const message = status === "confirmed" ? `The original ${kind} is confirmed.` : status === "submitted" ? "The original transaction is still confirming. Check this same intent ID again; do not repeat the deposit or withdrawal." : status === "prepared" ? "The original intent is prepared. This status check does not submit it. Check the same ID again or ask the operator to reconcile it before starting another operation." : "The original operation ended without a confirmed result. Reconcile its intent ID and transaction with the operator before starting another operation.";
+    return {
+      intentId,
+      kind,
+      wallet: this.signer.walletAddress,
+      vault: this.vault.address,
+      status,
+      requestedAmountRawUsdc: requested,
+      actualAmountRawUsdc: actual,
+      txSignature: record.txSignature,
+      errorCode: record.errorCode,
+      stillConfirming: status === "submitted",
+      nextAction,
+      message
+    };
+  }
   /**
    * Reads the yield budget. Syncs the relayer's ledger from chain first (so
    * yield accrued since the last sync shows up); the sync is best-effort and
@@ -2418,12 +2500,12 @@ if (submitted.txSignature !== null) {
 }
 if (submitted.status === "submitted") {
   fail(
-    `[deposit] broadcast but not yet confirmed \u2014 it may still land. Do NOT resubmit; check GET /v1/deposits/${submitted.depositId} (or the tx link above) first`
+    `[deposit] broadcast but not yet confirmed \u2014 it may still land. Do NOT resubmit; run pay status ${submitted.depositId} with the same wallet, vault and relayer first`
   );
 }
 if (submitted.status !== "confirmed") {
   fail(
-    `[deposit] not confirmed (errorCode=${submitted.errorCode}); check GET /v1/deposits/${submitted.depositId} and the relayer logs`
+    `[deposit] not confirmed (errorCode=${submitted.errorCode}); run pay status ${submitted.depositId} and ask the operator to reconcile it`
   );
 }
 console.log(