@candledottv/agent-sdk 0.4.11 → 0.6.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,187 @@ 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 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()`
+
+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.
+
+
+### 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. 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.
+
+### `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 +392,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