@candledottv/agent-sdk 0.4.10 → 0.5.0

package/dist/client.d.ts

@@ -26,11 +26,23 @@
  *   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";
 import type { AgentPlansResult, PlanPrice, PlanTable } from "./plans";
 import type { SecretStore } from "./secret-store";
+import type { CandleStaking } from "./staking";
 import { type WalletChain } from "./wallet-import";
 export type Chain = "solana" | "hood";
 /**
@@ -277,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;
@@ -462,6 +480,51 @@ export interface AgentProfile {
     launches: number;
     launchesViaApi: number;
 }
+/** How `listAgents` orders the directory, each largest first. */
+export type AgentDirectorySort = "newest" | "active" | "pnl";
+/** One published agent, as `listAgents` returns it. Identity and three aggregates: no wallet, no position. */
+export interface AgentDirectoryEntry {
+    /** The stable id, `prof_` and 16 hex. `GET /api/v1/agent/records/:profileId` reads its record. */
+    profileId: string;
+    /** The short address of the agent's page, `/agents/profile/<slug>`, or null. */
+    slug: string | null;
+    name: string;
+    avatarUrl: string | null;
+    bio: string | null;
+    owner: {
+        username: string | null;
+    };
+    strategy: string | null;
+    /** What the owner declared the agent runs on. Shown only: the directory has no model filter. */
+    models: string[];
+    /** Unix ms. */
+    publishedAt: number;
+    /** The newest trade or launch, unix ms. Null for an agent that has done neither. */
+    lastActiveAt: number | null;
+    /** All-time realized plus unrealized, USD, refreshed about every ten minutes. Null until first computed. */
+    totalPnlUsd: number | null;
+    tradeCount: number;
+    launchCount: number;
+    /** More launches exist than `launchCount` counted. */
+    launchesCapped: boolean;
+}
+/** One page of the directory. `cursor` is null on the last page, and always for a search. */
+export interface AgentDirectoryPage {
+    entries: AgentDirectoryEntry[];
+    cursor: string | null;
+}
+export interface ListAgentsOptions {
+    /** `newest` (default), `active` or `pnl`. */
+    sort?: AgentDirectorySort;
+    /** Keep one strategy category, such as `momentum`. An unknown one is refused with 400. */
+    strategy?: string;
+    /** Match the name, the slug or the owner's handle. At most 25 agents, unpaged. */
+    query?: string;
+    /** Agents per page, 1 to 48. Default 24. */
+    limit?: number;
+    /** The previous page's `cursor`. */
+    cursor?: string;
+}
 /**
  * GET /api/v1/agent/tier response, returned whole (same convention as `verify()`: the top-level
  * body IS the useful object, no envelope to unwrap). Dual auth: an agent key works here, and so
@@ -1402,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
@@ -2093,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. */
@@ -2145,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;
@@ -2165,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";
@@ -2188,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";
@@ -2220,6 +2343,9 @@ export declare class CandleClient {
     readonly wallets: CandleWallets;
     /** The creator fees this account's launched tokens can pay, and the claim (FE-438). */
     readonly fees: CandleFees;
+    /** Solana staking. The server supplies the pool wait and wallet eligibility notes. */
+    readonly staking: CandleStaking;
+    private stakingBuild;
     constructor(opts: CandleClientOptions);
     getQuotePairs(chain?: Chain): Promise<QuotePairsPayload>;
     getPresets(): Promise<PresetsPayload>;
@@ -2239,6 +2365,13 @@ export declare class CandleClient {
     getFeed(bucket: FeedBucket, chain?: Chain): Promise<FeedResult>;
     verify(chain: Chain, mint: string): Promise<VerifyResult>;
     getAgentProfile(idOrWallet: string): Promise<AgentProfile>;
+    /**
+     * The agent directory (`GET /api/v1/agent/directory`, no credential): every agent its owner
+     * published, one page at a time, including one that has never traded. Pass the returned
+     * `cursor` to read the next page; a page can be shorter than `limit` and still carry one. A
+     * server that predates the directory answers 404 (`CandleApiError`).
+     */
+    listAgents(options?: ListAgentsOptions): Promise<AgentDirectoryPage>;
     /**
      * The calling account's tier snapshot: display/live tier, staked/held CNDL, qualification
      * thresholds, grace window state, resolved fee bps, and lifetime fee totals by chain/asset.
@@ -2259,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>;
@@ -2465,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>;
     /**
@@ -2521,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
@@ -2620,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
@@ -2634,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
@@ -2646,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"
@@ -2667,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>;
     /**
@@ -2681,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
@@ -2769,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;
     /**
@@ -2799,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.10";
+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