@candledottv/agent-sdk 0.4.11 → 0.5.0

package/README.md

@@ -53,11 +53,13 @@ refuse to fetch without one and throw a plain `Error` locally instead of a serve
 
 `launch()` fills in a `clientLaunchId` (`"sdk-" + crypto.randomUUID()`) when you omit one, and
 retries transient failures by re-sending the SAME id, which the server's idempotency ledger
-resolves safely (no double mint, ever). Retries cover network errors, non-envelope 5xx
-responses, retryable 5xx envelopes, and the retryable in-flight 409; a non-retryable envelope
-(validation errors, an id reused with a different body, `LAUNCH_DISABLED`) is thrown
-immediately. Backoff is 250ms doubling per attempt, jittered, capped at 8s, bounded by
-`maxRetries` (default 3).
+resolves safely: no double mint inside one `launch()` call. That holds only inside the call. A
+second `launch()` call with no id is a new launch under a new id, so to retry after `launch()`
+throws, pass the id back: see "Retrying a write that failed or timed out" below. Retries cover
+network errors, non-envelope 5xx responses, retryable 5xx envelopes, and the retryable in-flight
+409; a non-retryable envelope (validation errors, an id reused with a different body,
+`LAUNCH_DISABLED`) is thrown immediately. Backoff is 250ms doubling per attempt, jittered, capped
+at 8s, bounded by `maxRetries` (default 3).
 
 ```ts
 import { CandleApiError } from "@candledottv/agent-sdk"
@@ -70,11 +72,12 @@ try {
     chain: "solana",
     buyAmount: 100_000_000, // lamports
   })
-  console.log("minted", result.mint, "explorer:", result.links.explorer)
+  console.log("minted", result.mint, "explorer:", result.links.explorer, "id:", result.clientLaunchId)
 } catch (error) {
   if (error instanceof CandleApiError) {
     // Branch on code, never on message. error.status, error.retryable, error.field ride along.
-    console.error("launch failed:", error.code)
+    // error.clientLaunchId is the id this call sent: keep it for the retry.
+    console.error("launch failed:", error.code, error.clientLaunchId)
   } else {
     throw error
   }
@@ -115,6 +118,8 @@ const fill = await candle.trade({ mint: "9dXSV8...CNDL", side: "buy", amountRaw:
   or from a linked wallet the caller signs for. Amounts are raw units. On Solana,
   `amounts.actualOutRaw` is the delivered amount, decoded from the payer's balance change; book
   positions from it rather than from `expectedOutRaw`. It is absent on Hood.
+- `getTradeJob(clientTradeId)` reads one trade from the idempotency ledger without sending
+  anything: the read to make after a `trade()` that threw or timed out. Needs `swap:write`.
 - `swap()` converts base assets (`SOL`, `USDC`, `CNDL`, `ETH`, `USDG`); a pair that spans Solana
   and Hood is a bridge.
 - `getPlans()` (no key) returns every plan's price, fees, limits and capabilities as the server
@@ -132,6 +137,135 @@ const fill = await candle.trade({ mint: "9dXSV8...CNDL", side: "buy", amountRaw:
 Limit orders are a REST surface only (`/api/v1/trade/agent/orders`); the SDK has no method for
 them.
 
+## Retrying a write that failed or timed out
+
+Six methods send an idempotency id, and generate one (`"sdk-" + crypto.randomUUID()`) when you
+pass none: `trade()`, `launch()`, `launchAsync()`, `selfLaunch()`, `buildAtomicLaunch()` and
+`launchAtomic()`. The server treats that id as the whole identity of the operation: the same id
+is a replay, and a new id is a second, independent trade or launch. A call that does not come
+back with a normal answer (a lost response, a proxy timeout, a 5xx) may still have executed, so
+what you do next depends on having the id.
+
+1. **Pass your own id for anything that moves funds, and store it before the call.** An error can
+   carry the id only if the process is still running to catch it. A crash or a kill mid-call
+   leaves nothing, and only an id you stored first survives that.
+2. **If you did not, read the id from the result or the error**, and send it back on the retry
+   with the same request body. Every one of the six methods exposes the id it sent on every
+   outcome: on the result (`result.clientTradeId`, `result.clientLaunchId`) and on every error
+   thrown after its first request was sent (`operationIds(error)`). This is the whole procedure
+   for the flows Candle executes. For `selfLaunch()` and a linked `trade()` it is not enough: see
+   below.
+3. **Never retry without the id.** A call with no id, or a new one, is a second trade or launch.
+   The SDK does not remember ids between calls and adds no retry of its own to `trade()`,
+   `selfLaunch()` or `launchAtomic()`; only `launch()` retries, inside its one call.
+
+What the error is:
+
+| The method threw | Class | The id |
+| --- | --- | --- |
+| a Candle error response | `CandleApiError`, unchanged | `error.clientTradeId` or `error.clientLaunchId`, and `error.bundleId` from `launchAtomic()` once its build answered |
+| a JSON-RPC failure from a broadcast | `JsonRpcError`, unchanged | the same fields |
+| a Hood trade whose fee leg failed after the trade landed | `TradeLandedFeeLegError`, unchanged | `error.clientTradeId` |
+| anything else after the first request was sent: a rejected `fetch`, a 2xx body that is not JSON, a plain `Error` from one of the method's own steps | `CandleOperationError`, with the original as `error.cause` | the same fields |
+| an error before anything was sent, such as no API key | the plain error | none: nothing reached the server, so there is nothing to replay |
+
+`operationIds(error)` returns `{ clientTradeId?, clientLaunchId?, bundleId? }` from any of these and
+`{}` from anything else, so a `catch (error: unknown)` block needs no cast. The ids are not secrets
+and may be logged. A `CandleOperationError`'s message starts with the original message, names the
+id, and says what to do with it.
+
+**Changed in 0.5.0:** a transport or local failure from these six methods used to surface as the
+raw error (a `TypeError` from `fetch`, for example). It is now a `CandleOperationError` with the
+original as `error.cause`. Code that matched `error instanceof TypeError` or
+`error.name === "AbortError"` on these calls should read `error.cause`. `launch()`, `selfLaunch()`,
+`confirmSelfLaunch()` and `buildAtomicLaunch()` results gained `clientLaunchId`, and
+`launchAtomic()` returns `LaunchAtomicResult`, its old result plus `clientLaunchId`.
+
+A main-payer trade (`from: "main"`), where the retry is safe once you have the id:
+
+```ts
+import { operationIds } from "@candledottv/agent-sdk"
+
+try {
+  return await candle.trade(req)
+} catch (error) {
+  const { clientTradeId } = operationIds(error)
+  if (!clientTradeId) throw error // nothing was sent
+  return await candle.trade({ ...req, clientTradeId }) // from: "main" only: a replay, not a second trade
+}
+```
+
+This example is not safe for a linked payer or for `selfLaunch()`: a same-id call there can
+broadcast again.
+
+### `trade()`
+
+With the id: read `getTradeJob(id)`, or call `trade()` again with the same id and body. Both are
+safe for a main payer.
+
+| The job read says | Meaning | Do |
+| --- | --- | --- |
+| 404 `JOB_NOT_FOUND` (thrown as `CandleApiError`) | the write never began | call again with the same id |
+| `confirmed` | the trade landed; `signature` is on the job | stop. A same-id `trade()` replays the result |
+| `failed`, `errorCode: "TRADE_REVERTED"` | it landed and reverted | a new trade needs a new id |
+| `failed`, other | not confirmed. A row with broadcast evidence may still be on chain, and a same-id call answers `stage: "unconfirmed"` for it. The same-id call is the check | call again with the same id |
+| `built` | in flight or unresolved | a same-id `trade()` answers `IDEMPOTENCY_CONFLICT`. If it carries `stage: "unconfirmed"` and `retryable: false`, check its `signature` on chain and do not retry |
+
+### `launch()`, `launchAsync()`
+
+Retry with the same `clientLaunchId` and body, or read `getLaunchJob(id)` (`waitForLaunch(id)`
+polls it). The rules are the ones under "Idempotency" in
+[Headless launch](https://docs.candle.tv/developers/headless-launch#idempotency); what is new is
+that you always have the id.
+
+### `selfLaunch()` and a linked `trade()`
+
+You sign and broadcast in these flows, so the id is necessary and **not** sufficient. An error
+after the broadcast may sit on a transaction that landed, and calling the method again under the
+same id builds and broadcasts a new one. So a `CandleOperationError` from these flows does not
+tell you to retry with the id. Read the job first (`getLaunchJob(id)`, `getTradeJob(id)`); if it
+is not `confirmed`, check the wallet's recent transactions before sending again.
+
+### `launchAtomic()`
+
+`launchAtomic()` returns `timeout` and `failed` as values, not errors, and each carries
+`clientLaunchId`. `bundleId` is dead once `/submit` has been called and is never resubmitted; it
+is on the result and the error for log correlation only. The launch's identity is
+`clientLaunchId`. After a `timeout` result, a `failed` result, or an error that carries
+`clientLaunchId`:
+
+1. Read `getLaunchJob(clientLaunchId)`. This needs `launch:read` on the key. The Write and
+   Withdraw access levels hold it; a key whose scopes were named one by one holds it only if it
+   was named, so add `launch:read` to any key that runs atomic launches. A scope refusal
+   (`SCOPE_MISSING`) is not "not found".
+2. `confirmed`: the bundle landed. The mint is on the job. Stop.
+3. 404 `JOB_NOT_FOUND`: the build never began. Call `launchAtomic()` again with the same id.
+4. `failed`: the bundle did not land. Call `launchAtomic()` again with the **same** id; the server
+   starts a clean attempt under it.
+5. Any other status: the bundle may still land. Wait, then either read the job again or call
+   `launchAtomic()` again with the **same** id and the same body. The server resolves the first
+   attempt before doing anything new. It answers 409 `IDEMPOTENCY_CONFLICT` while the first
+   attempt is unresolved or has just been found landed, so on that 409 read the job again. It
+   builds a fresh bundle only when the first is proven reverted.
+6. **Never send a new id while the job is not `failed`.** That is the one path the server cannot
+   refuse, and it is a second token. This includes the 409 whose message says "use a new
+   clientLaunchId to launch again": read the job first, because that message is also what you see
+   for a launch you do not yet know landed.
+7. One state has no terminal answer today. For an attempt whose blockhash expired with no
+   signature on record, the same-id `launchAtomic()` keeps answering 409 `IDEMPOTENCY_CONFLICT`,
+   "This launch was sent; its original attempt must be resolved", and the job read is still
+   neither `confirmed` nor `failed`. Treat it as this state when that remains true well after the
+   bundle's blockhash must have expired: a Solana blockhash lives about 90 seconds and a same-id
+   rebuild can itself take about 95 seconds, so a few minutes after the submit. Then stop. Do not
+   send a new id on a timer; report the `clientLaunchId` and `bundleId` to whoever operates the
+   key.
+8. Treat every `timeout` as unresolved. `retryable` is `false` on every `timeout` the server
+   returns today, and it is never permission to relaunch under a new id.
+
+A same-id rebuild can take up to about 95 seconds to answer, because the server waits on the
+chain, and a submit can take up to about 160 seconds. Set no client-side timeout shorter than
+that on these calls.
+
 ## Importing a wallet
 
 `importWallet()` drives Candle's ciphertext-only wallet import end to end: it fetches Privy's
@@ -206,7 +340,9 @@ Every non-2xx response throws `CandleApiError` with `code`, `status`, `retryable
 `docsPath` when the envelope carries them. Structured envelopes map straight through; the few
 legacy endpoints without envelopes (activity, users) surface as `code: "HTTP_<status>"`. A
 Solana or EVM JSON-RPC failure throws `JsonRpcError`, with the RPC's numeric `code` and its
-`data` (for a failed simulation, `{ err, logs }`). The full code table is on
+`data` (for a failed simulation, `{ err, logs }`). The one-call write methods also put the
+idempotency id they sent on these errors, and wrap any other failure in `CandleOperationError`:
+see "Retrying a write that failed or timed out" above. The full code table is on
 [Headless launch](https://docs.candle.tv/developers/headless-launch).
 
 ## Development

package/dist/client.d.ts

@@ -26,6 +26,17 @@
  *   validation error), and it never retries a launch whose stage is `executed` or `unconfirmed`
  *   or whose error already names a mint. Backoff is 250ms * 2^n, jittered to 50-100% of that,
  *   capped at 8s, bounded by `maxRetries` (default 3 retries after the initial attempt).
+ * - The id on every outcome. The six one-call write methods (`trade()`, `launch()`,
+ *   `launchAsync()`, `selfLaunch()`, `buildAtomicLaunch()`, `launchAtomic()`) send one idempotency
+ *   id per call, the caller's or a generated one, and once the first request carrying it has been
+ *   sent, every exit exposes that id: on the returned value, and on the thrown error
+ *   (`operationIds(error)`). A `CandleApiError` or `JsonRpcError` keeps its class and gains the id;
+ *   anything else (a rejected fetch, a 2xx body that is not JSON, a plain Error from one of the
+ *   method's own steps) is wrapped once, at the outermost method, in a `CandleOperationError` with
+ *   the original as `cause`. An error raised before anything was sent (no API key) carries no id
+ *   and is not wrapped. The SDK never reuses an id between calls and adds no retry of its own: a
+ *   call that passes no id is a new operation. The retry is the caller's, with the id passed back.
+ *   The README's "Retrying a write that failed or timed out" is the caller-facing procedure.
  */
 import { type HyperliquidNetwork, type HyperliquidTypedData } from "./hyperliquid";
 import type { HyperliquidPnlSection } from "./hyperliquid-pnl";
@@ -278,9 +289,15 @@ export interface SelfLaunchDryRunResult extends Omit<DryRunResult, "launchWallet
     launchWallet: string;
     launchWalletId: string;
 }
-/** POST /api/v1/launch/headless blocking (or replayed) success response. */
+/**
+ * POST /api/v1/launch/headless blocking (or replayed) success response, plus `clientLaunchId`.
+ * The server's body does not carry the id: `launch()`, `selfLaunch()` and `confirmSelfLaunch()`
+ * set it from the request they sent, so a caller who let the SDK generate it still has it.
+ */
 export interface LaunchResult {
     success: true;
+    /** The idempotency id this launch was sent under, the caller's or the generated one. */
+    clientLaunchId: string;
     chain: Chain;
     mint: string;
     pool: string | null;
@@ -1448,6 +1465,42 @@ export type ConfirmTradeRequest = {
 };
 /** POST /api/v1/trade/agent/confirm response. Always "executed": confirm only ever verifies and records a trade that already happened on-chain. */
 export type ConfirmTradeResult = ExecutedTradeResult;
+/**
+ * One trade from the idempotency ledger, from GET /api/v1/trade/agent/jobs/:clientTradeId
+ * (`getTradeJob()`). `amountRaw` is raw units: the quote asset's on a buy, the token's on a sell.
+ * `status` is `built` (in flight, or built and never confirmed), `confirmed` (landed; `signature`
+ * is set) or `failed` (`errorCode` says why; `TRADE_REVERTED` means it landed and reverted).
+ */
+export interface TradeJob {
+    clientTradeId: string;
+    chain: Chain;
+    side: TradeSide;
+    mint: string;
+    quoteAsset: string;
+    amountRaw: string;
+    status: "built" | "confirmed" | "failed";
+    signature?: string;
+    errorCode?: string;
+    createdAt: number;
+    updatedAt: number;
+    /** A Hood TEE trade only: its sequenced operation, leg by leg. `kind` and `status` are open strings. */
+    operation?: {
+        operationId: string;
+        kind: string;
+        status: string;
+        plannedLegCount: number;
+        currentLegIndex: number;
+        legs: Array<{
+            kind: string;
+            status: string;
+            hash?: string;
+            nonce?: number;
+        }>;
+        expiresAt: number;
+        /** The fee a trade that landed after its lock expired still owes, once the read has recorded it. */
+        feeOwed?: Record<string, unknown>;
+    };
+}
 /**
  * POST /api/v1/trade/agent/submit request body. `signedTransactions` is the ordered signed legs:
  * one for Solana; one to four for Hood in the fixed approval, permit2Approval, trade, feeTransfer
@@ -2139,7 +2192,10 @@ export interface TradeRequest {
      * The server defaults it when omitted, which is `sol` on Solana and ETH settlement on Hood.
      */
     quoteAsset?: "sol" | "usdc" | "cndl" | "eth" | "usdg";
-    /** Idempotency key shared by the build and confirm calls; generated ("sdk-" + UUID) when omitted. */
+    /**
+     * Idempotency key shared by the build and confirm calls; generated ("sdk-" + UUID) when omitted.
+     * Pass your own for anything that moves funds and store it before the call: see `trade()`.
+     */
     clientTradeId?: string;
 }
 /** selfLaunch()'s one-call request: BuildSelfLaunchRequest plus the linked wallet's Privy wallet id. */
@@ -2191,8 +2247,14 @@ export interface AtomicBundleResponseLeg {
         amountOutRaw: string;
     };
 }
-/** POST /api/v1/launch/atomic/build response. */
+/**
+ * POST /api/v1/launch/atomic/build response, plus `clientLaunchId`. The server's body does not
+ * carry the id: `buildAtomicLaunch()` sets it from the request it sent. It is the launch's
+ * identity (`bundleId` is single-use), so a caller driving build and submit by hand keeps it.
+ */
 export interface BuildAtomicLaunchResult {
+    /** The idempotency id this build was sent under, the caller's or the generated one. */
+    clientLaunchId: string;
     bundleId: string;
     legs: AtomicBundleResponseLeg[];
     expiresAt: number;
@@ -2211,14 +2273,21 @@ export interface SubmitAtomicLaunchRequest {
  * are the 502 body -- all three are NORMAL, expected outcomes of submitting a Jito bundle that
  * this route documents as part of its own response surface, so `submitAtomicLaunch()`/
  * `launchAtomic()` return them here rather than throwing `CandleApiError` (every OTHER non-2xx
- * status still throws, same as every other method). `retryable` is always `false` for `"failed"`;
- * for `"timeout"` it is `true` only when the bundle's shared blockhash was proven to have expired
- * with no confirmation -- `false` means the resolution window simply ran out with no definitive
- * answer and the bundle MIGHT STILL LAND, so the caller should wait rather than immediately
- * rebuild under a fresh `clientLaunchId`. In every case, `bundleId` itself is dead once this
- * response arrives: it is consumed on the first `/submit` call regardless of outcome, so recovery
- * is always a fresh `buildAtomicLaunch()`/`launchAtomic()` call, never a retried `submit` with the
- * same id. See "Atomic launch with first buys" in docs/headless-launch.md for the full model.
+ * status still throws, same as every other method).
+ *
+ * `retryable` is `false` on every `"failed"` and on every `"timeout"` the server returns today.
+ * It is not permission to relaunch, whatever its value: a `"timeout"` means the resolution window
+ * ran out with no definitive answer and the bundle MIGHT STILL LAND. Treat every `"timeout"` as
+ * unresolved and never rebuild under a new `clientLaunchId` because of one: that is a second
+ * token. (This comment used to describe a `true` case meaning "the blockhash expired, relaunch".
+ * No server path returns it.)
+ *
+ * `bundleId` itself is dead once this response arrives: it is consumed on the first `/submit`
+ * call regardless of outcome and is never resubmitted. The launch's identity is the
+ * `clientLaunchId` the build was sent under, and recovery goes through it: read
+ * `getLaunchJob(clientLaunchId)`, then call `launchAtomic()` again with the SAME id when the job
+ * says to (the steps are on `launchAtomic()`). See "Atomic launch with first buys" in
+ * docs/headless-launch.md for the full model.
  */
 export type SubmitAtomicLaunchResult = {
     status: "landed";
@@ -2234,6 +2303,14 @@ export type SubmitAtomicLaunchResult = {
     bundleId: string;
     retryable: boolean;
 };
+/**
+ * What `launchAtomic()` returns: `submitAtomicLaunch()`'s outcome plus the `clientLaunchId` the
+ * launch was sent under, on all three of `landed`, `failed` and `timeout`. `submitAtomicLaunch()`
+ * itself is given only a `bundleId` and cannot know the launch id.
+ */
+export type LaunchAtomicResult = SubmitAtomicLaunchResult & {
+    clientLaunchId: string;
+};
 /** Who pays for one leg of launchAtomic()'s one-call request. Mirrors AtomicLaunchPayer, but a "linked" payer also carries the privyWalletId signLinkedTransaction() needs to sign that leg -- mirrors TradeRequest's `from` field. */
 export type LaunchAtomicPayer = {
     type: "main";
@@ -2315,12 +2392,27 @@ export declare class CandleClient {
     /**
      * Blocking launch with idempotent retries. Generates `clientLaunchId` when absent and
      * re-sends the SAME id on retryable failures; see the module doc for the exact policy.
+     *
+     * The id this call sent, yours or the generated one, is on the result
+     * (`result.clientLaunchId`) and on every error thrown after the first request was sent
+     * (`operationIds(error).clientLaunchId`), including the one thrown when the retries run out.
+     * The built-in retries are safe only inside this one call. To retry after it throws, call
+     * `launch()` again with that SAME id and the same body, or read `getLaunchJob(id)`. Never retry
+     * without the id: a call with no id, or a new one, is a second launch. Pass your own id and
+     * store it before the call when you can: an error can carry the id only if the process is
+     * still running to catch it.
      */
     launch(req: LaunchRequest): Promise<LaunchResult>;
     /**
      * Fire-and-poll launch: sends `async: true`, returns the 202 body. Single attempt (poll
      * `waitForLaunch` instead of retrying the POST). Generates `clientLaunchId` like `launch()`
      * so the returned body always carries the id to poll.
+     *
+     * An error thrown after the request was sent carries that id too
+     * (`operationIds(error).clientLaunchId`): the launch may have been accepted. Poll
+     * `getLaunchJob(id)` / `waitForLaunch(id)`, or call again with the SAME id and body. Never
+     * retry without the id: a call with no id, or a new one, is a second launch. Pass your own id
+     * and store it before the call when you can.
      */
     launchAsync(req: LaunchRequest): Promise<AcceptedJob>;
     getLaunchJob(clientLaunchId: string): Promise<LaunchJob>;
@@ -2521,11 +2613,14 @@ export declare class CandleClient {
      * docs/headless-launch.md.
      */
     buildSelfLaunch(req: BuildSelfLaunchRequest): Promise<BuildSelfLaunchResult>;
+    /** buildSelfLaunch()'s request; selfLaunch() passes its `op` so its exits can expose the id. */
+    private postSelfLaunchBuild;
     /**
      * Self-signed launch confirm: verifies the agent's own broadcast on-chain, then records the
      * launch identically to the headless path. Signature is the transaction hash from the agent's
      * own broadcast. devBuySignature (Hood only) is the optional follow-up dev-buy transaction. See
-     * selfLaunch() below for the one-call version of this whole flow (Solana).
+     * selfLaunch() below for the one-call version of this whole flow (Solana). The result carries
+     * the `clientLaunchId` from the request (the server's body does not).
      */
     confirmSelfLaunch(req: ConfirmSelfLaunchRequest): Promise<ConfirmSelfLaunchResult>;
     /**
@@ -2577,6 +2672,30 @@ export declare class CandleClient {
      *   `built | confirmed | failed`.
      */
     buildTrade(req: BuildTradeRequest): Promise<BuildTradeResult>;
+    /** buildTrade()'s request; trade() passes its `op` so its exits can expose the id. */
+    private postTradeBuild;
+    /**
+     * Reads one trade from the idempotency ledger by its `clientTradeId`, without sending
+     * anything: the read to make after a `trade()` that threw or timed out, before deciding whether
+     * to send again. Needs `swap:write` (the scope the trade itself needed) and answers during a
+     * kill switch.
+     *
+     * - 404 `JOB_NOT_FOUND` (a thrown `CandleApiError`): the write never began. Call again with the
+     *   same id.
+     * - `confirmed`: the trade landed; `signature` is on the job. A same-id `trade()` replays it.
+     * - `failed` with `errorCode: "TRADE_REVERTED"`: it landed and reverted. A new trade needs a
+     *   new id.
+     * - `failed`, other: not confirmed. A row with broadcast evidence may still be on chain; a
+     *   same-id `trade()` is the check, and answers `IDEMPOTENCY_CONFLICT` with
+     *   `stage: "unconfirmed"` for it.
+     * - `built`: in flight or unresolved. A same-id `trade()` answers `IDEMPOTENCY_CONFLICT`; if it
+     *   carries `stage: "unconfirmed"` and `retryable: false`, check its `signature` on chain and
+     *   do not retry.
+     *
+     * For a linked payer, also check the wallet's recent transactions before sending again: see
+     * `trade()`.
+     */
+    getTradeJob(clientTradeId: string): Promise<TradeJob>;
     /**
      * Confirm a LINKED payer's own broadcast trade: Candle verifies it landed on-chain, that it was
      * actually signed/sent by the declared linked wallet, that it moved this trade's own mint in
@@ -2676,8 +2795,30 @@ export declare class CandleClient {
      *   opt-in, but only for a caller that has already confirmed the build carries neither an
      *   `approval` nor a `permit2Approval` leg. Requires `evmRpcUrl`; throws a clear error
      *   naming it when unset, before any RPC read or signing.
+     *
+     * ## The id, and retrying
+     *
+     * The `clientTradeId` this call sent, yours or the generated one, is on the result and on every
+     * error thrown after the build request was sent (`operationIds(error).clientTradeId`): a
+     * `CandleApiError` or `JsonRpcError` gains it, and a lost response or any other failure is a
+     * `CandleOperationError` carrying it, with the original as `cause`. Pass your own id for
+     * anything that moves funds and store it before the call: an error can carry the id only if
+     * the process is still running to catch it. Never retry without the id: a call with no id, or a
+     * new one, is a second, independent trade. This method does not retry on its own.
+     *
+     * - **Main payer** (`from: "main"`): the trade executes inside the build call, so a lost
+     *   response can sit on a trade that already moved funds. With the id, read `getTradeJob(id)`
+     *   or call `trade()` again with the same id and body. Both are safe: the same-id call is a
+     *   replay, not a second trade. `getTradeJob()`'s jsdoc says what each job state means.
+     * - **Linked payer**: the id is necessary and NOT sufficient. The caller's side signs and
+     *   broadcasts here, so an error after the broadcast may sit on a transaction that landed, and
+     *   calling again under the same id can build and broadcast a second one. Read
+     *   `getTradeJob(id)` first; if it is not `confirmed`, check the wallet's recent transactions
+     *   before sending again.
      */
     trade(req: TradeRequest): Promise<ExecutedTradeResult>;
+    /** trade()'s steps. Every error leaves through trade()'s runOperation(), which adds the id. */
+    private tradeSteps;
     /**
      * One-call self-signed launch. Solana: `buildSelfLaunch` -> `signLinkedTransaction` ->
      * `broadcastSignedTransaction` -> `confirmSelfLaunch` (`built.transaction` is a base64 unsigned
@@ -2690,8 +2831,23 @@ export declare class CandleClient {
      * send a dev buy: a Hood self-launch's dev buy is a separate transaction the caller sends itself
      * and reports to `confirmSelfLaunch` as `devBuySignature`. The build response never includes a
      * dev-buy leg, and this method does not assemble one.
+     *
+     * ## The id, and retrying
+     *
+     * The `clientLaunchId` this call sent, yours or the generated one, is on the result and on every
+     * error thrown after the build request was sent (`operationIds(error).clientLaunchId`). Pass
+     * your own id and store it before the call when you can. Never retry without the id: a call
+     * with no id, or a new one, is a second, independent launch.
+     *
+     * Here the id is necessary and NOT sufficient. This method signs and broadcasts on the caller's
+     * side, so an error after the broadcast may sit on a launch transaction that landed, and
+     * calling `selfLaunch()` again under the same id can build and broadcast a second one. Read
+     * `getLaunchJob(id)` first; if it is not `confirmed`, check the wallet's recent transactions
+     * before sending again.
      */
     selfLaunch(req: SelfLaunchRequest): Promise<ConfirmSelfLaunchResult>;
+    /** selfLaunch()'s steps. Every error leaves through selfLaunch()'s runOperation(), which adds the id. */
+    private selfLaunchSteps;
     /**
      * Builds an atomic launch bundle: a Solana launch transaction plus 1-4 first-buy transactions,
      * all sharing one recent blockhash so Jito lands them together or not at all. Returns the
@@ -2702,8 +2858,22 @@ export declare class CandleClient {
      * the full model: Pro/Max tier, `launch:write` + `swap:write` scopes, Solana only, the 1-4 buy
      * cap (Jito's 5-transaction bundle limit), and why every buy leg's own on-chain `minAmountOut` is
      * "0" inside the bundle (`expectedFill` on the returned legs is the real consent surface).
+     *
+     * The result carries the `clientLaunchId` the build was sent under (the server's body does
+     * not), and so does every error thrown after the request was sent
+     * (`operationIds(error).clientLaunchId`). Keep it: `bundleId` is single-use, and the launch's
+     * identity for any later read or retry is the `clientLaunchId`. Retry a failed build with the
+     * SAME id and body, or read `getLaunchJob(id)`; a call with no id, or a new one, is a second
+     * launch. After a submit, follow the steps on `launchAtomic()`. Pass your own id and store it
+     * before the call when you can.
      */
     buildAtomicLaunch(req: BuildAtomicLaunchRequest): Promise<BuildAtomicLaunchResult>;
+    /**
+     * The atomic build request itself. Sets `clientLaunchId` on the result from the request, since
+     * the server's body omits it. Shared by buildAtomicLaunch() and launchAtomic(), each of which
+     * runs it inside its OWN runOperation(), so an error is wrapped once, by the outermost method.
+     */
+    private postAtomicBuild;
     /**
      * Submits an already-built bundle's client-signer legs (EXACTLY the ones
      * `BuildAtomicLaunchResult.legs` named `signer: "client"`, in leg order -- omit every "server"
@@ -2723,7 +2893,15 @@ export declare class CandleClient {
      * roughly 150-160s in the worst case (Jito's own ~60s poll budget plus a further ~90s resolution
      * phase), since Candle checks the launch signature's own on-chain status before answering. Set a
      * client-side timeout no shorter than ~160s (or none) for this call, or you risk abandoning a
-     * request that was about to return a normal, if late, response.
+     * request that was about to return a normal, if late, response. A same-id
+     * `buildAtomicLaunch()`/`launchAtomic()` after a send can itself take up to about 95 seconds to
+     * answer, because the server resolves the first attempt against the chain before doing anything
+     * new: allow for that too.
+     *
+     * This method is given only a `bundleId`, so its result cannot carry the launch's
+     * `clientLaunchId`. Keep the one `buildAtomicLaunch()` returned: after a `"failed"` or
+     * `"timeout"`, recovery goes through it (the steps are on `launchAtomic()`), never through
+     * this `bundleId` and never through a new id.
      */
     submitAtomicLaunch(req: SubmitAtomicLaunchRequest): Promise<SubmitAtomicLaunchResult>;
     /**
@@ -2737,11 +2915,44 @@ export declare class CandleClient {
      * bundle with no linked payer at all (every leg "main") skips the signing round entirely and
      * goes straight from build to submit.
      *
-     * Returns `submitAtomicLaunch()`'s own result untouched -- see that method's jsdoc for why
-     * `"failed"`/`"timeout"` are returned here rather than thrown, and for the recommended
-     * client-side timeout.
-     */
-    launchAtomic(req: LaunchAtomicRequest): Promise<SubmitAtomicLaunchResult>;
+     * Returns `submitAtomicLaunch()`'s outcome plus the `clientLaunchId` the launch was sent under
+     * (`LaunchAtomicResult`), on `"landed"`, `"failed"` and `"timeout"` alike -- see that method's
+     * jsdoc for why `"failed"`/`"timeout"` are returned here rather than thrown, and for the
+     * recommended client-side timeout. A thrown error carries `clientLaunchId` too, and `bundleId`
+     * once the build has answered (`operationIds(error)`). Pass your own id and store it before the
+     * call when you can: an error can carry the id only if the process is still running to catch it.
+     *
+     * ## After a `timeout`, a `failed`, or an error that carries `clientLaunchId`
+     *
+     * `bundleId` is dead once `/submit` has been called and is never resubmitted; it is for log
+     * correlation only. The launch's identity is `clientLaunchId`:
+     *
+     * 1. Read `getLaunchJob(clientLaunchId)`. It needs `launch:read` on the key; a key whose scopes
+     *    were named by hand holds it only if it was named. A scope refusal is not "not found".
+     * 2. `confirmed`: the bundle landed. The mint is on the job. Stop.
+     * 3. 404 `JOB_NOT_FOUND`: the build never began. Call `launchAtomic()` again with the same id.
+     * 4. `failed`: the bundle did not land. Call `launchAtomic()` again with the SAME id; the server
+     *    starts a clean attempt under it.
+     * 5. Any other status: the bundle may still land. Wait, then read the job again or call
+     *    `launchAtomic()` again with the SAME id and the same body. The server resolves the first
+     *    attempt before doing anything new. It answers 409 `IDEMPOTENCY_CONFLICT` while the first
+     *    attempt is unresolved or has just been found landed, so on that 409 read the job again. It
+     *    builds a fresh bundle only when the first is proven reverted. This same-id call can take
+     *    about 95 seconds to answer, because the server waits on the chain.
+     * 6. Never send a new id while the job is not `failed`: that is a second token. This includes
+     *    the 409 whose message says "use a new clientLaunchId to launch again": read the job first,
+     *    because that message is also what a caller sees for a launch it does not yet know landed.
+     * 7. One state has no terminal answer today. The same-id call keeps answering 409 "This launch
+     *    was sent; its original attempt must be resolved" and the job is neither `confirmed` nor
+     *    `failed`, still, a few minutes after the submit (a blockhash lives about 90 seconds and the
+     *    rebuild itself can take about 95). Stop: do not send a new id on a timer, and report the
+     *    `clientLaunchId` and `bundleId` to whoever operates the key.
+     * 8. Treat every `timeout` as unresolved. `retryable` is `false` on every one the server returns
+     *    today, and it is never permission to relaunch under a new id.
+     */
+    launchAtomic(req: LaunchAtomicRequest): Promise<LaunchAtomicResult>;
+    /** launchAtomic()'s steps. Every error leaves through launchAtomic()'s runOperation(), which adds the ids. */
+    private launchAtomicSteps;
     /**
      * The `EvmRpc` seam packages/sdk/src/evm-tx.ts's helpers are built against, built from this
      * client's own `jsonRpcCall`/`jsonRpcCallRaw` closed over `evmRpcUrl`. Callers must have already
@@ -2825,6 +3036,17 @@ export declare class CandleClient {
     private signLinkedTypedData;
     private requireKey;
     private headers;
+    /**
+     * Runs a one-call write method's steps so that every exit exposes the idempotency id it sent
+     * (see the module doc, "The id on every outcome"). The steps pass `op` to the request that
+     * carries the id. Until that request is handed to fetch, an error leaves unchanged: nothing
+     * reached the server, so there is nothing to replay. After it, `withOperationIds()` puts the
+     * ids on a `CandleApiError`/`JsonRpcError` and wraps anything else in a `CandleOperationError`.
+     *
+     * Called once per public method, never nested: an inner step that is itself a one-call method
+     * (launchAtomic()'s build) runs its plain request, so the error is wrapped once, here.
+     */
+    private runOperation;
     private requestJson;
     private parseResponse;
     /**
@@ -2855,7 +3077,7 @@ export declare function __setEvmReceiptWaitForTest(opts: {
     pollMs?: number;
 } | null): void;
 /** This build's own version. Kept in lockstep with package.json by the release-bump CI guard. */
-export declare const SDK_VERSION = "0.4.11";
+export declare const SDK_VERSION = "0.5.0";
 /** Test seam: the once-per-process latch would otherwise weld the suite's first case to the rest. */
 export declare function __resetSdkUpdateNoticeForTest(): void;
 //# sourceMappingURL=client.d.ts.map