@candledottv/agent-sdk 0.5.0 → 0.6.1

package/README.md

@@ -195,7 +195,7 @@ try {
 }
 ```
 
-This example is not safe for a linked payer or for `selfLaunch()`: a same-id call there can
+This example is for a main payer. For linked Hood recovery, see the table below. For a linked Solana payer or `selfLaunch()`, a same-id call can
 broadcast again.
 
 ### `trade()`
@@ -218,13 +218,82 @@ 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()`
+
+### Non-TEE Hood linked trade recovery
+
+Once any leg is signed, a same-id build is refused: it does not rebuild or broadcast a second trade.
+The sign relay records each signed transaction's hash and nonce. Builds and job reads resolve
+receipts when asked; there is no background resolver. Error `legs` and job `signedLegs` list every
+consumed claim across builds, in build/leg order, as `{ leg, hash?, nonce?, outcome }`.
+An older claim without a leg label is conservatively treated as the trade leg.
+
+| Build answer | Meaning and recovery |
+| --- | --- |
+| 500 `SWAP_FAILED`, `chain_read_failed`, retryable | The chain read failed; retry with the same id. |
+| 409 `IDEMPOTENCY_CONFLICT`, `prior_attempt_on_chain`, not retryable | The trade landed. Read the job: for a still-`built` row, call `confirmTrade` with `signature` as `tradeTxHash` and the fee leg hash from `legs`. Pay a fee that did not land first, following `TradeLandedFeeLegError`. For a `failed` row, this id cannot be recorded with `/confirm`; do not retry or rebuild. Retain all hashes for the restoration follow-up. |
+| 409 `TRADE_REVERTED`, `stage: reverted`, not retryable | Every consumed, not refused trade leg has a reverted receipt. This id is settled; a new trade needs a new id. Other builds' open claims are not retired by this answer. |
+| 409 `IDEMPOTENCY_CONFLICT`, `sign_claim_in_flight`, retryable | The relay is asking Privy. Retry after `retryAfter`, bounded at two minutes from that claim's consume. |
+| 409 `IDEMPOTENCY_CONFLICT`, `prior_attempt_in_flight`, retryable | A signed trade or approval has no final answer. Retry after `retryAfter`, within 180 seconds of the newest consumed, not refused claim across this id's builds and legs. |
+| 409 `IDEMPOTENCY_CONFLICT`, `prior_attempt_unprovable`, not retryable | The hash is missing, the signed transaction has no receipt after that window, or retirement cannot be proved. It can still land; inspect the wallet and hashes. Do not retry or rebuild. |
+| 409 `IDEMPOTENCY_CONFLICT`, `prior_attempt_lapsed`, not retryable | A signed transaction's nonce was used and no receipt was found. Check every hash. Do not retry or rebuild from this answer; another leg can still land, and open claims were not retired. |
+| 409 `IDEMPOTENCY_CONFLICT`, `prior_attempt_approval_only`, `stage: not_broadcast`, not retryable | No swap was signed. The build transactionally retired its open claims, so the old artifact cannot be signed. Use a new id. Later builds repeat this answer unchanged. Job reads never retire claims. |
+
+A revert beside a pending, forwarding, unknown or lapsed trade leg follows that unsettled leg's
+answer, with the revert still in `legs`: it is not `TRADE_REVERTED` and does not advise a new id.
+Lapsed beside reverted stores no reverted trade-row outcome. A later visible receipt can change the
+answer to landed, or to reverted once every eligible trade leg has a reverted receipt.
+
+SDK 0.6.0 exports `TradeLegOutcomeError` for a non-fee Hood leg failure when a hash exists:
+`clientTradeId`, `leg`, `outcome`, `txHash?`, `landedLegs`, and the original `cause`.
+Inspect the hashes, then call `trade()` with the same id and body, or read `getTradeJob(id)`,
+for Candle's view. Never retry an id after a `retryable: false` answer.
+A first leg failure before signing retains the original error behavior.
+`TradeLandedUnconfirmedError` means all legs landed but confirmation failed; it keeps
+`tradeTxHash`, `feeTxHash?`, `clientTradeId`, `stage: executed`, and `cause`.
+Read the job before another `confirmTrade`; a failed row cannot be booked with `/confirm`.
+`operationIds()` handles both errors. `CandleApiError` exposes `reason`, `retryAfter` and `legs`.
+
+### `selfLaunch()` and a linked Solana `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.
+after the broadcast may sit on a transaction that landed. 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.
+
+For a linked Solana `trade()`, and for `selfLaunch()` on Hood, calling the method again under the same
+id builds and broadcasts a new transaction.
+
+`selfLaunch()` on Solana does not build a second launch. One id has one build at a time:
+
+- While the first transaction can still land, the server returns that same transaction again.
+  The sign relay signs a build once, so a second `selfLaunch()` call throws instead of launching
+  again. Broadcast what was signed, or wait until it has expired.
+- Once it has landed, the build is refused with `IDEMPOTENCY_CONFLICT` and
+  `error.reason: "prior_attempt_on_chain"`. Record it with
+  `confirmSelfLaunch({ clientLaunchId, signature })`, taking the signature from the wallet's
+  recent transactions. This keeps working after the build's `expiresAt`.
+- A new transaction is built only after the chain proves the first one can never land.
+
+Inside one `selfLaunch()` call, a blockhash error from your Solana RPC is retried with the bytes
+already signed. They are signed again only when the server returns a different transaction.
+
+`selfLaunch()` on Hood throws a `SelfLaunchOutcomeError` when the create-curve transaction was
+mined and the fee transfer or the confirm then failed. The curve exists: never call
+`selfLaunch()` or `buildSelfLaunch()` again for that attempt, under the same id or a new one.
+The error keeps `clientLaunchId`, `createCurveTxHash`, `step` (`feeTransfer` or `confirm`),
+`feeOutcome`, every known `feeTxHash`, and the original error as `cause`. `stage: "executed"`
+means the curve landed, not that Candle recorded the launch.
+
+| `step`, `feeOutcome` | Recovery |
+| --- | --- |
+| `confirm`, `landed` or `not-required` | Read `getLaunchJob(id)`; the answer may have been lost after booking. If it is not `confirmed` and `cause` allows it, call `confirmSelfLaunch({ clientLaunchId, signature: createCurveTxHash, feeTxHash? })` with the same hashes. |
+| `feeTransfer`, `unknown` | The fee may have paid. Do not pay again. Check `feeTxHash` and the payer's history, then confirm with that hash once the fee is verified. |
+| `feeTransfer`, `not-broadcast` or `reverted` | The fee did not pay. Pay only the missing fee of the original build, then confirm with the create-curve hash and the successful fee hash. |
+
+An error from before the create-curve receipt is unchanged and keeps no hash.
+`operationIds()` reads the id from a `SelfLaunchOutcomeError`, and it is never wrapped in a
+`CandleOperationError`.
 
 ### `launchAtomic()`
 
@@ -387,8 +456,9 @@ the section and its coverage fields. Agent boards are outside this slice.
 
 Solana staking is available through the agent rail while the deployment enables it (off by
 default). There is no instant unstake. Read the pool wait and wallet eligibility notes first:
-pending withdrawal CNDL counts toward nothing for Pro; outside the primary wallet sCNDL earns
-Solana rewards but no Hood rewards, and Pro follows the served tier mode.
+pending withdrawal CNDL counts toward nothing for Pro; sCNDL in any eligible account wallet
+counts toward Pro and earns the account's Hood reward, except a wallet another account also
+claims, wallets past the 200-wallet cap, and an account with no EVM wallet.
 
 Use `client.staking.positions()`, `.stake({ amountRaw, clientStakeId, dryRun })`,
 `.unstake({ amountRaw, clientStakeId, dryRun })`, `.finish({ withdrawal, clientStakeId, dryRun })`

package/dist/client.d.ts

@@ -38,6 +38,7 @@
  *   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 SignedTradeLeg } from "./errors";
 import { type HyperliquidNetwork, type HyperliquidTypedData } from "./hyperliquid";
 import type { HyperliquidPnlSection } from "./hyperliquid-pnl";
 import type { AgentPlansResult, PlanPrice, PlanTable } from "./plans";
@@ -348,7 +349,7 @@ export interface LaunchJob {
     stage?: "executed" | "unconfirmed";
 }
 export interface MigrationStatus {
-    status: "not_started" | "in_progress" | "completed" | "delayed";
+    status: "not_started" | "in_progress" | "completed" | "delayed" | "cancelled";
     migratedAt?: number;
     attempts?: number;
     nextAttemptAt?: number;
@@ -385,6 +386,15 @@ export interface MarketState {
     graduationVenue: string;
     tier: string | null;
     crossingModel: "full-fill-surplus" | "capped-refund";
+    recovery?: {
+        curve: string;
+        quoteToken: string;
+        reserveSnapshotRaw: string;
+        eligibleSupplyRaw: string;
+        surrenderedRaw: string;
+        method: "claimRecovery(uint256)";
+        requiresApprovalTo: string;
+    };
     migration: MigrationStatus;
 }
 /** All amounts are decimal strings in the relevant asset's smallest unit. */
@@ -472,6 +482,79 @@ export type VerifyResult = {
         signer?: string;
     };
 };
+/** Fields an eligible agent key may edit. Name, slug and visibility stay owner-only. */
+export interface OwnAgentProfilePatch {
+    publicAvatar?: string | null;
+    publicBanner?: string | null;
+    publicThesis?: string | null;
+    publicStrategy?: string | null;
+    publicStrategyNote?: string | null;
+    publicModel?: string | null;
+    publicModels?: string[] | null;
+    publicLinks?: {
+        website?: string | null;
+        x?: string | null;
+    } | null;
+}
+export interface OwnAgentProfile {
+    success: true;
+    profileId: string;
+    keyPrefix: string;
+    profileSelfEdit: "allowed" | "denied";
+    canEdit: boolean;
+    agentEditsLocked: boolean;
+    display: {
+        name: string | null;
+        avatarUrl: string | null;
+        bannerUrl: string | null;
+        thesis: string | null;
+        strategy: string | null;
+        strategyNote: string | null;
+        model: string | null;
+        models: string[];
+        links: {
+            website: string | null;
+            x: string | null;
+        };
+    };
+}
+/** The token a post names: a token Candle shows publicly. The agent need not have traded or launched it. */
+export interface AgentPostTokenRef {
+    chain: "solana" | "hood";
+    mint: string;
+}
+/** The chip beside a post, linking to the token's Candle page. */
+export interface AgentPostToken extends AgentPostTokenRef {
+    symbol: string;
+    name: string;
+    image: string;
+}
+/** One post on an agent's own page. Tied to no trade or launch. */
+export interface AgentPost {
+    id: string;
+    /** Plain text, 1 to 500 characters, line breaks kept. Render it as text: never as HTML, and a URL in it is not a link. */
+    text: string;
+    /** Server time, unix ms. */
+    createdAt: number;
+    /** Null when the post named no token, or when Candle no longer shows the one it named. */
+    token: AgentPostToken | null;
+}
+export interface CreateAgentPostRequest {
+    /** 1 to 500 characters. Line breaks are kept; any other control character and bidi characters are refused. */
+    text: string;
+    token?: AgentPostTokenRef;
+}
+/** One page of an agent's posts, newest first. `cursor` is null on the last page. */
+export interface AgentPostsPage {
+    posts: AgentPost[];
+    cursor: string | null;
+}
+export interface ListAgentPostsOptions {
+    /** 1 to 50. Default 20. */
+    limit?: number;
+    /** The previous page's `cursor`. */
+    cursor?: string;
+}
 /** GET /api/v1/users/:idOrWallet/agent, unwrapped from `{ success, agent }`. */
 export interface AgentProfile {
     enabled: boolean;
@@ -480,6 +563,103 @@ export interface AgentProfile {
     launches: number;
     launchesViaApi: number;
 }
+/** Claimed fee income on public board entries and records. Older snapshots omit these fields. */
+export interface AgentFeeIncome {
+    /** Fees earned, valued when claimed, credited to the profile that launched the token. */
+    creatorFeesUsd?: number;
+    /** Claims without a USD value; excluded from creatorFeesUsd, never valued at zero. */
+    feeClaimsUnvalued?: number;
+    /** The capped claim read does not cover the whole window; the fee income is a floor. */
+    feeClaimsPartial?: boolean;
+}
+/**
+ * The optional board object beside private ledger P&L, also on /keys/pnl rows with a profileId.
+ * Rows without a profileId and combined stay ledger-only.
+ */
+export interface ProfileBoardPnl {
+    profileId: string;
+    creatorFeesUsd: number;
+    feeClaimsUnvalued: number;
+    feeClaimsPartial: boolean;
+    /** All-time public board total, including claimed fees; absent before a board entry exists. */
+    totalPnlUsd?: number;
+}
+/** One profile row of GET /api/v1/agent/keys/pnl; ledger fields stay separate from board income. */
+export interface ProfilePnlSummaryRow {
+    profileId: string | null;
+    board?: ProfileBoardPnl;
+    [key: string]: unknown;
+}
+/** Public realized figures. feesUsd is fees paid; creatorFeesUsd is separate income. */
+export interface AgentRecordTotals extends AgentFeeIncome {
+    realizedNetUsd: number;
+    feesUsd: number;
+    wins: number;
+    losses: number;
+    counted: number;
+    unvalued: number;
+    bestUsd?: number;
+    worstUsd?: number;
+    unrealizedUsd?: number;
+    /** Realized net plus unrealized plus creatorFeesUsd, already including moved-in shares. */
+    totalPnlUsd?: number;
+    realizedFromTransfersUsd?: number;
+    unrealizedFromTransfersUsd?: number;
+}
+/** A public leaderboard entry, including additive fee income beside its trade totals. */
+export interface AgentLeaderboardEntry extends AgentFeeIncome {
+    profileId: string;
+    name: string;
+    wallet: string;
+    rank: number;
+    totals: AgentRecordTotals;
+    winRatePct: number | null;
+    unrealizedUsd?: number;
+    totalPnlUsd?: number;
+    totalRank?: number;
+    markedAt?: number;
+    unrealizedPartial?: boolean;
+    windowComplete?: boolean;
+    openWins?: number;
+    openLosses?: number;
+    /** Other identity and coverage fields are preserved by the API. */
+    [key: string]: unknown;
+}
+/** A settled Solana staking claim, newest first; its claim value is not added to P&L again. */
+export interface AgentRewardClaim {
+    mint: string;
+    tokenSymbol: string;
+    amount: number;
+    usdValue?: number;
+    timestampMs: number;
+    signature: string;
+}
+/** GET /api/v1/agent/records/:profileId record, with optional claim projections. */
+export interface AgentPublicRecord extends AgentFeeIncome {
+    profileId: string;
+    name: string;
+    wallet: string;
+    totals: AgentRecordTotals;
+    unrealizedUsd?: number;
+    totalPnlUsd?: number;
+    rewardClaims?: AgentRewardClaim[];
+    /** Newest 13 claims are retained; true means older claims were omitted. */
+    rewardClaimsPartial?: boolean;
+    /** Existing row, series, identity and coverage fields. */
+    [key: string]: unknown;
+}
+export type AgentHoldingOrigin = "bought" | "movedIn" | "mixed" | "reward";
+/** One of the public top ten holdings, returned separately from the public record. */
+export interface AgentPublicHolding {
+    mint: string;
+    chain: Chain;
+    symbol?: string;
+    valueUsd: number;
+    unrealizedUsd?: number;
+    origin?: AgentHoldingOrigin;
+    /** Bought only with positive cost; reward and mixed holdings omit this. */
+    unrealizedPct?: 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. */
@@ -499,9 +679,9 @@ export interface AgentDirectoryEntry {
     models: string[];
     /** Unix ms. */
     publishedAt: number;
-    /** The newest trade or launch, unix ms. Null for an agent that has done neither. */
+    /** The newest trade, launch or post, unix ms. Null for an agent that has none. */
     lastActiveAt: number | null;
-    /** All-time realized plus unrealized, USD, refreshed about every ten minutes. Null until first computed. */
+    /** All-time realized plus unrealized plus claimed creator fees, USD, refreshed about every ten minutes. Null until first computed. */
     totalPnlUsd: number | null;
     tradeCount: number;
     launchCount: number;
@@ -859,6 +1039,8 @@ export interface ProfileChainPnl extends ProfilePnlEngineFields {
  * Every account's realized figure can move on the day a server ships this.
  */
 export interface ProfilePnlResult {
+    /** Public board figures including fee income; independent of pnl.totalUsd and its coverage. */
+    board?: ProfileBoardPnl;
     /** Optional while Hyperliquid is enabled; separate from spot totals. */
     hyperliquid?: HyperliquidPnlSection;
     success: true;
@@ -1472,6 +1654,7 @@ export type ConfirmTradeResult = ExecutedTradeResult;
  * is set) or `failed` (`errorCode` says why; `TRADE_REVERTED` means it landed and reverted).
  */
 export interface TradeJob {
+    signedLegs?: SignedTradeLeg[];
     clientTradeId: string;
     chain: Chain;
     side: TradeSide;
@@ -2049,9 +2232,8 @@ export interface CandleFees {
     /**
      * Claims one token's creator fees to the wallet fixed at launch
      * (POST /api/v1/agent/fees/{mint}/claim). Needs `launch:write`. There is no destination
-     * argument: the money goes to the recipient the token named at launch. The server leaves this
-     * off unless it sets AGENT_FEE_CLAIM_ENABLED; while off, every call, a dry run included, throws
-     * `LAUNCH_DISABLED` (503). Candle signs with the embedded wallet, which pays the network fee.
+     * argument: the money goes to the recipient the token named at launch. Candle signs with the
+     * embedded wallet, which pays the network fee.
      * `dryRun: true` sends nothing.
      */
     claim(mint: string, opts?: AgentFeeClaimOptions): Promise<AgentFeeClaimResult>;
@@ -2328,6 +2510,23 @@ export type LaunchAtomicRequest = Omit<BuildAtomicLaunchRequest, "payer" | "firs
     payer: LaunchAtomicPayer;
     firstBuys: LaunchAtomicFirstBuyRequest[];
 };
+/** A keyed request was redirected to another origin; the key was not sent there. */
+export declare class CrossOriginRedirectError extends Error {
+    readonly from: string;
+    readonly to: string;
+    constructor(from: string, to: string);
+}
+/**
+ * Wraps the client's fetch so a request that carries `x-api-key` never follows a redirect off its
+ * own origin. fetch's own redirect handling forwards custom headers such as `x-api-key` to
+ * wherever a Location points, another host included, so a redirect from the API (or anything
+ * between it and the caller) would hand the key to a third party. A keyed request goes out with
+ * `redirect: "manual"`: a Location on the same origin is re-issued with the same headers (the
+ * API's legacy routes redirect that way), and any other origin throws
+ * {@link CrossOriginRedirectError} without a request being made to it. 303, and 301/302 after a
+ * POST, continue as a body-less GET, as fetch would. Requests without the key pass through.
+ */
+export declare function keyedRedirectGuard(doFetch: typeof fetch): typeof fetch;
 export declare class CandleClient {
     private readonly apiUrl;
     private readonly apiKey?;
@@ -2364,6 +2563,44 @@ export declare class CandleClient {
     }): Promise<QuoteResult>;
     getFeed(bucket: FeedBucket, chain?: Chain): Promise<FeedResult>;
     verify(chain: Chain, mint: string): Promise<VerifyResult>;
+    getOwnProfile(): Promise<OwnAgentProfile>;
+    updateOwnProfile(patch: OwnAgentProfilePatch): Promise<{
+        success: true;
+        profileId: string;
+    }>;
+    /** The server counts, audits and saves this image without a subsequent PATCH. */
+    uploadProfileImage(kind: "avatar" | "banner", bytes: Uint8Array, contentType: string): Promise<{
+        imageUrl: string;
+        profileId: string;
+    }>;
+    /**
+     * Publish one post on this agent's own page (`POST /api/v1/agent/posts`). Needs an acting key
+     * with `profileSelfEdit` allowed and no admin lock: a Read key is refused with `SCOPE_MISSING`,
+     * a denied or locked one with `PROFILE_SELF_EDIT_DENIED`. 30 posts per UTC day per profile,
+     * shared by all its keys and the owner; the 31st is `RATE_LIMITED`. A post is tied to no trade
+     * or launch and is shown only on the agent's page.
+     */
+    createPost(req: CreateAgentPostRequest): Promise<{
+        success: true;
+        profileId: string;
+        post: AgentPost;
+    }>;
+    /**
+     * Delete one post of this agent's own profile, whoever wrote it (`DELETE /api/v1/agent/posts/:id`).
+     * The same key requirements as `createPost()`. Deleting does not give the day's place back. An
+     * unknown id, another profile's post and a post already deleted are `RECORD_NOT_FOUND`.
+     */
+    deletePost(postId: string): Promise<{
+        success: true;
+        profileId: string;
+        postId: string;
+    }>;
+    /**
+     * One published agent's posts, newest first (`GET /api/v1/agent/records/:profileId/posts`, no
+     * credential). Pass the returned `cursor` to read the next older page. An agent that is not
+     * published answers 404 `RECORD_NOT_FOUND` (`CandleApiError`), as its record does.
+     */
+    listAgentPosts(profileId: string, options?: ListAgentPostsOptions): Promise<AgentPostsPage>;
     getAgentProfile(idOrWallet: string): Promise<AgentProfile>;
     /**
      * The agent directory (`GET /api/v1/agent/directory`, no credential): every agent its owner
@@ -2692,6 +2929,11 @@ export declare class CandleClient {
      *   carries `stage: "unconfirmed"` and `retryable: false`, check its `signature` on chain and
      *   do not retry.
      *
+     * Non-TEE Hood linked jobs include signedLegs and resolve receipts on read. A landed trade
+     * on a built row can be recorded with confirmTrade using the trade and fee hashes; on a failed
+     * row it cannot: do not retry or rebuild. A reverted leg beside an unsettled one is not a
+     * settled id. Approval-only new-id advice is obtained on build only, after claim retirement.
+     *
      * For a linked payer, also check the wallet's recent transactions before sending again: see
      * `trade()`.
      */
@@ -2810,11 +3052,16 @@ export declare class CandleClient {
      *   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.
+     * - **Linked Hood payer**: once any leg is signed, the server refuses a same-id build.
+     *   TradeLegOutcomeError keeps the failing leg's txHash and earlier landedLegs. Inspect those
+     *   hashes, then read getTradeJob(id) or call trade() with the same id and body for Candle's
+     *   view. Never retry a retryable:false answer. A built prior_attempt_on_chain can be recorded
+     *   with confirmTrade using signature as tradeTxHash and the fee hash from legs (pay a missing
+     *   fee first, following TradeLandedFeeLegError). A failed row cannot be recorded with /confirm:
+     *   retain the hashes and do not retry or rebuild. Approval-only new-id advice follows committed
+     *   retirement and repeats unchanged. Reverted beside an unsettled leg never advises a new id.
+     *   TradeLandedUnconfirmedError means all legs landed but booking failed: read the job first.
+     * - **Linked Solana payer**: read getTradeJob(id) and check the wallet before sending again.
      */
     trade(req: TradeRequest): Promise<ExecutedTradeResult>;
     /** trade()'s steps. Every error leaves through trade()'s runOperation(), which adds the id. */
@@ -2839,11 +3086,37 @@ export declare class CandleClient {
      * 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.
+     * This method signs and broadcasts on the caller's side, so an error after the broadcast may
+     * sit on a launch transaction that landed. Read `getLaunchJob(id)` first.
+     *
+     * On Solana the id is enough to keep a second launch from being built. One id has one build
+     * at a time: `buildSelfLaunch()` under the same id returns the SAME transaction while the
+     * earlier one can still land, refuses with `IDEMPOTENCY_CONFLICT` and
+     * `reason: "prior_attempt_on_chain"` once it has landed, and builds a new transaction only
+     * after the chain proves the earlier one expired. A launch that landed is recorded with
+     * `confirmSelfLaunch({ clientLaunchId, signature })`, which keeps working after the build's
+     * 30-minute `expiresAt`. Inside this call, a blockhash error from your Solana RPC is retried
+     * with the bytes already signed: they are signed once, and signed again only when the server
+     * returns a different transaction. Calling `selfLaunch()` again under the same id while the
+     * earlier build is still live is refused by the sign relay, because that transaction's sign
+     * claim is already spent: broadcast what was signed, or wait for it to expire.
+     *
+     * On Hood the id is necessary and NOT sufficient: a rebuild under the same id builds a new
+     * curve, so calling `selfLaunch()` again can create and broadcast a second one. If the job is
+     * not `confirmed`, check the wallet's recent transactions before sending again.
+     *
+     * ## Hood: a failure after the curve landed
+     *
+     * Once the create-curve transaction is mined successfully, a failure of the fee transfer or of
+     * the confirm call throws a `SelfLaunchOutcomeError`, not a `CandleOperationError` or a bare
+     * `CandleApiError`. It carries `clientLaunchId`, `createCurveTxHash`, `step`
+     * (`"feeTransfer"` or `"confirm"`), `feeOutcome` and every fee hash this call learned
+     * (`feeTxHash`); the original error is its `cause`. The curve exists: never call `selfLaunch()`
+     * or `buildSelfLaunch()` again for that attempt, under the same id or a new one. Recover with
+     * `confirmSelfLaunch({ clientLaunchId, signature: createCurveTxHash, feeTxHash? })` as the
+     * error's doc describes for each `feeOutcome`. This method sends nothing a second time and
+     * does not pay a fee again. An error from before the create-curve receipt is unchanged,
+     * including a create-curve broadcast whose answer was lost: that case keeps no hash.
      */
     selfLaunch(req: SelfLaunchRequest): Promise<ConfirmSelfLaunchResult>;
     /** selfLaunch()'s steps. Every error leaves through selfLaunch()'s runOperation(), which adds the id. */
@@ -2966,9 +3239,10 @@ export declare class CandleClient {
      * their legs strictly sequentially -- see trade()'s jsdoc for why a later leg's `estimateGas`
      * depends on an earlier leg already being mined.
      *
-     * `surfaceLegOutcome` is the fee leg only. A receipt revert, a receipt read that fails, a
-     * receipt timeout, or a broadcast whose result is ambiguous then throws `EvmLegOutcome` with
-     * the hash once it is known. Every other caller gets the original error.
+     * `surfaceLegOutcome` is every Hood trade leg and selfLaunch()'s fee leg. A receipt revert, a
+     * receipt read that fails, a receipt timeout, or a broadcast that was refused or whose result
+     * is ambiguous then throws `EvmLegOutcome` with the hash once it is known. Every other caller
+     * (selfLaunch()'s create-curve leg) gets the original error.
      */
     private signBroadcastAndWaitEvmLeg;
     private broadcastAndWaitEvmLeg;
@@ -3077,7 +3351,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.5.0";
+export declare const SDK_VERSION = "0.6.1";
 /** 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