@settlemint/dalp-sdk 3.1.33 → 3.2.0-rc.1

package/dist/server-proxy.js

@@ -0,0 +1,186 @@
+import"./chunk-k3ntysxx.js";
+import {
+  normalizeDalpBaseUrl
+} from "./chunk-crtb9edj.js";
+
+// ../wire/http-contract/src/trusted-client-address.ts
+import { isIP } from "node:net";
+var validAddress = (value) => {
+  const trimmed = value?.trim();
+  return trimmed !== undefined && isIP(trimmed) !== 0 ? trimmed : undefined;
+};
+var appendedForwardedFor = (headers) => validAddress(headers.get("x-forwarded-for")?.split(",").at(-1));
+function readTrustedClientAddress(input) {
+  const { headers, profile } = input;
+  if (profile === "envoy") {
+    return validAddress(headers.get("x-envoy-external-address") ?? undefined) ?? appendedForwardedFor(headers);
+  }
+  if (profile === "nginx" || profile === "openshift") {
+    return appendedForwardedFor(headers);
+  }
+  return;
+}
+
+// src/server-proxy.ts
+var HOP_BY_HOP_HEADERS = [
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade"
+];
+var TRUSTED_FORWARDING_HEADERS = [
+  "forwarded",
+  "forwarded-for",
+  "x-forwarded",
+  "x-forwarded-for",
+  "x-forwarded-host",
+  "x-forwarded-port",
+  "x-forwarded-prefix",
+  "x-forwarded-proto",
+  "x-forwarded-client-cert",
+  "x-original-forwarded-for",
+  "x-real-ip",
+  "x-client-ip",
+  "x-cluster-client-ip",
+  "x-envoy-external-address",
+  "x-envoy-downstream-remote-address",
+  "x-envoy-original-host",
+  "x-envoy-original-path",
+  "cf-connecting-ip",
+  "true-client-ip",
+  "fastly-client-ip"
+];
+var STRIPPED_REQUEST_HEADERS = [...HOP_BY_HOP_HEADERS, ...TRUSTED_FORWARDING_HEADERS, "host", "content-length"];
+function createDalpProxy(options) {
+  const upstream = normalizeDalpBaseUrl(String(options.upstream));
+  const origin = options.origin === undefined ? undefined : new URL(String(options.origin)).origin;
+  const trustedProxyProfile = options.trustedProxyProfile ?? "none";
+  const acceptEncoding = options.acceptEncoding ?? "identity";
+  const fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  const onUpstreamFailure = options.onUpstreamFailure ?? (() => {});
+  const upstreamFailureMessage = options.upstreamFailureMessage ?? ((path) => `The service behind ${path} did not answer. Retry after a short delay.`);
+  return async (request) => {
+    const requestUrl = new URL(request.url);
+    const targetUrl = `${upstream}${requestUrl.pathname}${requestUrl.search}`;
+    const hasBody = request.method !== "GET" && request.method !== "HEAD";
+    const init = {
+      method: request.method,
+      headers: sanitizeRequestHeaders(request.headers, trustedProxyProfile, origin, acceptEncoding),
+      body: hasBody ? request.body : undefined,
+      duplex: hasBody ? "half" : undefined,
+      decompress: false,
+      redirect: "manual",
+      signal: request.signal
+    };
+    let response;
+    try {
+      response = await fetch(targetUrl, init);
+    } catch (error) {
+      if (hasBody || request.signal.aborted || !isConnectionReset(error)) {
+        return upstreamFailure(request, upstream, onUpstreamFailure, upstreamFailureMessage, error);
+      }
+      try {
+        response = await fetch(targetUrl, init);
+      } catch (retryError) {
+        return upstreamFailure(request, upstream, onUpstreamFailure, upstreamFailureMessage, retryError);
+      }
+    }
+    const isRedirect = response.status >= 300 && response.status < 400;
+    const isNullBody = response.status === 204 || response.status === 205 || isRedirect;
+    const contentType = response.headers.get("content-type") ?? "";
+    const isStream = contentType.includes("text/event-stream") || contentType.includes("application/x-ndjson");
+    let body = null;
+    if (!isNullBody) {
+      if (isStream) {
+        body = response.body ?? "";
+      } else {
+        try {
+          body = await response.arrayBuffer();
+        } catch (error) {
+          return upstreamFailure(request, upstream, onUpstreamFailure, upstreamFailureMessage, error);
+        }
+      }
+    }
+    const headers = sanitizeResponseHeaders(response.headers);
+    if (isNullBody) {
+      headers.delete("content-length");
+      headers.delete("content-encoding");
+      headers.delete("content-type");
+      headers.delete("transfer-encoding");
+    }
+    return new Response(body, { status: response.status, statusText: response.statusText, headers });
+  };
+}
+function sanitizeRequestHeaders(original, profile, origin, acceptEncoding) {
+  const headers = Object.fromEntries(original.entries());
+  if (headers.origin === undefined && origin !== undefined) {
+    headers.origin = origin;
+  }
+  if (acceptEncoding === "identity") {
+    headers["accept-encoding"] = "identity";
+  }
+  const trustedSignal = readTrustedClientSignal(original, profile);
+  for (const name of STRIPPED_REQUEST_HEADERS) {
+    Reflect.deleteProperty(headers, name);
+  }
+  if (trustedSignal !== undefined) {
+    headers[trustedSignal.name] = trustedSignal.value;
+  }
+  return headers;
+}
+function sanitizeResponseHeaders(original) {
+  const headers = new Headers(original);
+  for (const name of HOP_BY_HOP_HEADERS) {
+    headers.delete(name);
+  }
+  return headers;
+}
+function readTrustedClientSignal(headers, profile) {
+  const value = readTrustedClientAddress({ headers, profile });
+  return value === undefined ? undefined : { name: profile === "envoy" ? "x-envoy-external-address" : "x-forwarded-for", value };
+}
+function upstreamFailure(request, upstream, onUpstreamFailure, upstreamFailureMessage, error) {
+  if (request.signal.aborted) {
+    return new Response(null, { status: 499, headers: { "cache-control": "no-store" } });
+  }
+  const cause = error instanceof Error ? error : undefined;
+  const code = readErrorCode(error);
+  const route = new URL(request.url).pathname;
+  onUpstreamFailure({
+    method: request.method,
+    path: route,
+    upstream: new URL(upstream).origin,
+    errorName: cause?.name ?? typeof error,
+    errorMessage: cause?.message ?? String(error),
+    errorCode: code
+  });
+  return Response.json({
+    status: 502,
+    code: "UPSTREAM_UNAVAILABLE",
+    message: upstreamFailureMessage(route)
+  }, { status: 502, headers: { "cache-control": "no-store" } });
+}
+function isConnectionReset(error) {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  if (readErrorCode(error) === "ECONNRESET") {
+    return true;
+  }
+  const message = error.message.toLowerCase();
+  return message.includes("socket connection was closed") || message.includes("connection was closed");
+}
+function readErrorCode(error) {
+  if (!(error instanceof Error)) {
+    return;
+  }
+  const code = Reflect.get(error, "code");
+  return typeof code === "string" || typeof code === "number" ? String(code) : undefined;
+}
+export {
+  createDalpProxy
+};

package/dist/sign-webhook-receipt.d.ts

@@ -0,0 +1,16 @@
+export declare const RECEIPT_SIGNING_SCHEME = "dalp.whr.v1";
+export interface ReceiptSigningTuple {
+    deliveryId: string;
+    endpointId: string;
+    evtId: string;
+    innerEventHash: string;
+}
+export interface SignWebhookReceiptInput extends ReceiptSigningTuple {
+    secret: string;
+}
+export declare function buildReceiptSigningString(tuple: Readonly<ReceiptSigningTuple>): string;
+export declare function signWebhookReceipt({ secret, ...tuple }: Readonly<SignWebhookReceiptInput>): string;
+export interface VerifyWebhookReceiptInput extends SignWebhookReceiptInput {
+    readonly signature: string;
+}
+export declare function verifyWebhookReceipt({ signature, ...input }: Readonly<VerifyWebhookReceiptInput>): boolean;

package/dist/sign-webhook-receipt.js

@@ -0,0 +1,26 @@
+import {
+  toStandardWebhookSecret2
+} from "./chunk-g5j1xky8.js";
+
+// src/sign-webhook-receipt.ts
+import { createHmac, timingSafeEqual } from "node:crypto";
+var RECEIPT_SIGNING_SCHEME = "dalp.whr.v1";
+function buildReceiptSigningString(tuple) {
+  return [RECEIPT_SIGNING_SCHEME, tuple.deliveryId, tuple.endpointId, tuple.evtId, tuple.innerEventHash].join(`
+`);
+}
+function signWebhookReceipt({ secret, ...tuple }) {
+  const key = Buffer.from(toStandardWebhookSecret2(secret), "base64");
+  return createHmac("sha256", key).update(buildReceiptSigningString(tuple), "utf8").digest("hex");
+}
+function verifyWebhookReceipt({ signature, ...input }) {
+  const expected = Buffer.from(signWebhookReceipt(input), "hex");
+  const received = Buffer.from(signature, "hex");
+  return expected.length === received.length && timingSafeEqual(expected, received);
+}
+export {
+  RECEIPT_SIGNING_SCHEME,
+  buildReceiptSigningString,
+  signWebhookReceipt,
+  verifyWebhookReceipt
+};

package/dist/transport/cookie-store.d.ts

@@ -0,0 +1,9 @@
+export type CookieStoreFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export interface CookieStoreShape {
+    readonly header: () => string;
+    readonly isEmpty: () => boolean;
+    readonly setCookieHeader: (header: string) => void;
+    readonly storeSetCookieHeaders: (headers: ReadonlyArray<string>) => void;
+}
+export declare function makeCookieStore(initialHeader?: string): CookieStoreShape;
+export declare function createCookieStoreFetch(cookieStore: CookieStoreShape, fetchImpl?: CookieStoreFetch): CookieStoreFetch;

package/dist/transport/sse-lifecycle.d.ts

@@ -0,0 +1,24 @@
+export type SseEventDisposition = "continue" | "success" | "failure";
+export interface SseStreamResult<T> {
+    readonly stream: AsyncIterable<T>;
+}
+export interface SseLifecycleOptions<T> {
+    readonly connect: (signal: AbortSignal) => Promise<SseStreamResult<T>>;
+    readonly classify: (event: T) => SseEventDisposition;
+    readonly signal?: AbortSignal;
+    readonly onEvent?: (event: T) => void;
+    readonly maxReconnects?: number;
+    readonly reconnectWindowMs?: number;
+    readonly healthyConnectionMs?: number;
+    readonly initialBackoffMs?: number;
+    readonly maxBackoffMs?: number;
+    readonly sleep?: (milliseconds: number) => Promise<void>;
+    readonly now?: () => number;
+}
+export type SseLifecycleFailureReason = "aborted" | "terminal-failure" | "transport-failure";
+export declare class SseLifecycleError<T = unknown> extends Error {
+    readonly reason: SseLifecycleFailureReason;
+    readonly lastEvent?: T;
+    constructor(reason: SseLifecycleFailureReason, lastEvent?: T, options?: ErrorOptions);
+}
+export declare function consumeSseUntilTerminal<T>(options: SseLifecycleOptions<T>): Promise<T>;

package/dist/types.d.ts

@@ -1,115 +1,39 @@
-/**
- * Type-only exports for the DALP SDK.
- *
- * Import from `@settlemint/dalp-sdk/types` when you only need types
- * (e.g., for function signatures) without pulling in runtime code.
- *
- * Related: kit/sdk/src/client.ts
- *
- * @module
- */
-import type { DalpApi } from "./api-types.generated.js";
-/**
- * Fully typed DALP API client.
- *
- * The shapes come from `./api-types.generated.ts` rather than from the contract
- * router's inferred type. A declaration that names the contract cannot be
- * published: `@dalp/api-contract` is private, and the inferred type does not
- * survive declaration emit at all (`TS7056` on the larger route files). See
- * `./contract.ts`.
- *
- * Response values carry the wire representation, so a `bigint` field reads as a
- * decimal string and a timestamp as an ISO string. The client serializes on the
- * way out but does not decode on the way back, so a request may pass either the
- * native value or its string form.
- *
- * Provides auto-completed access to all v2 API namespaces:
- * `account`, `actions`, `addons`, `admin`, `contacts`, `exchangeRates`,
- * `externalToken`, `identityRecovery`, `monitoring`, `search`,
- * `settings`, `system`, `token`, `transaction`, `user`.
- */
-export type DalpClient = DalpApi;
-/**
- * Per-call client context threaded into individual SDK operations as the second
- * argument, e.g. `client.token.create(input, { context: { idempotencyKey } })`.
- * Every field is optional and scoped to the single call, unlike the client-level
- * {@link BaseDalpClientConfig.idempotencyKey} which applies to every request.
- */
-export interface DalpClientCallContext {
-    /**
-     * Idempotency key sent as the `Idempotency-Key` header for this call only,
-     * overriding any client-level key. Use a fresh value per genuine retry of a
-     * failed mutation: dapi burns the key of a failed transaction, so re-sending
-     * under the same key is rejected ("previously failed. Use a new idempotency
-     * key to retry"). A stable value within one logical attempt keeps network-level
-     * fetch retries deduplicated.
-     */
-    idempotencyKey?: string;
-    /**
-     * oRPC error codes the caller treats as expected for this call and does not
-     * want surfaced by its own error logging (e.g. an existence probe that accepts
-     * `NOT_FOUND`). A client-side hint scoped to the single call; it is not sent to
-     * the server.
-     */
-    skipLoggingFor?: readonly string[];
+import type { AssumableParticipant, JoinableParticipant, JoinableProvider, EvmAddress, TokenTopicScheme, TokenTrustedIssuer, EvmUserEventV2Item, UserEventV2Item, UserMe, party_multisigDrafts_issueInvite_Response, party_topicSchemes_addForToken_Request, party_trustedIssuers_addForToken_Request, party_users_activityStats_Response, party_users_events_Response, platform_settings_settingsThemeUploadLogo_Request, token_create_Request, token_documents_getUploadUrl_Request, token_features_list_Response, system_feeds_issuerSigned_create_Request } from "./generated/api-types.ts";
+export type ParticipantKind = "person" | "company" | "fund" | "spv" | "department" | "joint_account" | "asset" | "organisation" | "claim_issuer" | "addon" | "agent";
+export type ParticipantAddressPurpose = "transfer" | "identity" | "participant";
+export interface EligibleForTokenFilter {
+    readonly tokenAddress: EvmAddress;
+    readonly action: "mint" | "transfer" | "burn";
+    readonly reveal?: boolean;
 }
-interface BaseDalpClientConfig {
-    /** Base URL of the DALP API (e.g., `"https://dalp.example.com"`). */
-    url: string;
-    /**
-     * Organization ID for multi-tenant setups.
-     * Required when the API key is scoped to multiple organizations.
-     */
-    organizationId?: string;
-    /**
-     * Additional headers merged into every request.
-     * Accepts a static object or a (possibly async) function for dynamic headers.
-     * Can override defaults like `User-Agent` but cannot override security headers (`x-api-key`, `x-organization-id`).
-     */
-    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
-    /**
-     * Validate outgoing requests against the contract before sending.
-     * Catches schema violations client-side for faster feedback.
-     * @defaultValue false
-     */
-    requestValidation?: boolean;
-    /**
-     * Validate incoming responses against the contract.
-     * Useful during development to catch API drift.
-     * @defaultValue false
-     */
-    responseValidation?: boolean;
-    /**
-     * Custom `fetch` implementation.
-     * Use this to inject logging, proxy configuration, or test doubles.
-     */
-    fetch?: typeof globalThis.fetch;
-    /**
-     * Idempotency key sent as the `Idempotency-Key` header on every request.
-     *
-     * **Warning:** This value is sent on _every_ request made by the client.
-     * If you reuse the same client instance for multiple mutations, the server
-     * will deduplicate all but the first — subsequent mutations silently return
-     * the first response. Only set this when the client is used for a single
-     * mutation (e.g., a one-shot script). For multi-mutation workflows, set the
-     * header per-request via the `headers` callback instead.
-     *
-     * When omitted, no idempotency key header is sent.
-     */
-    idempotencyKey?: string;
-}
-/**
- * Configuration for creating an authenticated DALP API client.
- */
-export interface DalpClientConfig extends BaseDalpClientConfig {
-    /** API key for authenticated routes (issued via the DALP dashboard or CLI). */
-    apiKey: string;
-}
-/**
- * Configuration for creating a public DALP API client.
- */
-export interface PublicDalpClientConfig extends BaseDalpClientConfig {
-    apiKey?: undefined;
-}
-export type { WalletAuthEndpointPath } from "./auth-wallet-plugins.js";
-//# sourceMappingURL=types.d.ts.map
+export type JoinableParticipantOption = JoinableParticipant;
+export type JoinableProviderOption = JoinableProvider;
+export type ActAvailability = AssumableParticipant["actAvailability"];
+export type OnboardingState = UserMe["onboardingState"];
+export type UserEvent = UserEventV2Item;
+export type EvmUserEvent = EvmUserEventV2Item;
+export type UserEventCollectionResponse = party_users_events_Response;
+export type UserActivityChartResponse = party_users_activityStats_Response;
+export type UserEventValue = NonNullable<EvmUserEvent["values"]>[number];
+export type TokenTopicSchemeInheritanceLevel = TokenTopicScheme["inheritanceLevel"];
+export type TokenTrustedIssuerInheritanceLevel = TokenTrustedIssuer["inheritanceLevel"];
+export type TokenTopicSchemeCreateInput = party_topicSchemes_addForToken_Request;
+export type TokenTrustedIssuerCreateInput = party_trustedIssuers_addForToken_Request;
+export type MultisigDraftCreateInviteOutput = party_multisigDrafts_issueInvite_Response;
+export type IssuerSignedCreateInput = system_feeds_issuerSigned_create_Request;
+export type ThemeLogoMode = platform_settings_settingsThemeUploadLogo_Request["mode"];
+type AttachedTokenFeature = token_features_list_Response["data"][number];
+type AttachedTokenFeatureConfig<Name extends AttachedTokenFeature["name"]> = NonNullable<Extract<AttachedTokenFeature, {
+    readonly name: Name;
+}>["config"]>;
+export type TokenFeatureHistoricalBalancesConfig = AttachedTokenFeatureConfig<"historical-balances">;
+export type TokenFeatureMaturityRedemptionConfig = AttachedTokenFeatureConfig<"maturity-redemption">;
+export type TokenFeatureFixedTreasuryYieldConfig = AttachedTokenFeatureConfig<"fixed-treasury-yield">;
+export type TokenFeatureDividendYieldConfig = AttachedTokenFeatureConfig<"dividend-yield">;
+export type TokenFeatureInterestYieldConfig = AttachedTokenFeatureConfig<"interest-yield">;
+export type TokenFeatureTransactionFeeConfig = AttachedTokenFeatureConfig<"transaction-fee">;
+export type TokenFeatureTransactionFeeAccountingConfig = AttachedTokenFeatureConfig<"transaction-fee-accounting">;
+export type TokenFeatureExternalTransactionFeeConfig = AttachedTokenFeatureConfig<"external-transaction-fee">;
+export type TokenDocumentMimeType = token_documents_getUploadUrl_Request["mimeType"];
+export type TokenCreateInput = token_create_Request;
+export type * from "./generated/api-types.ts";

package/dist/url.d.ts

@@ -1,2 +1 @@
 export declare function normalizeDalpBaseUrl(url: string): string;
-//# sourceMappingURL=url.d.ts.map

package/dist/verify-webhook.d.ts

@@ -1,34 +1,24 @@
-import type { Webhook } from "./webhook-events.js";
-export type WebhookVerificationFailure = "TIMESTAMP_SKEW" | "SECRET_MISMATCH" | "BODY_HASH_MISMATCH";
+import type { Webhook } from "./webhook-events.ts";
+export type WebhookVerificationFailure = "TIMESTAMP_SKEW" | "SECRET_MISMATCH" | "BODY_HASH_MISMATCH" | "REPLAYED_EVENT" | "MALFORMED_BODY" | "REPLAY_STORE_FAILURE";
 export type WebhookVerificationResult = {
-    ok: true;
-    event: Webhook.Event;
+    readonly ok: true;
+    readonly event: Webhook.Event;
+    readonly release: () => Promise<void>;
 } | {
-    ok: false;
-    code: WebhookVerificationFailure;
+    readonly ok: false;
+    readonly code: WebhookVerificationFailure;
 };
+export interface WebhookReplayStore {
+    readonly claim: (eventId: string, claimId: string) => boolean | Promise<boolean>;
+    readonly release: (eventId: string, claimId: string) => void | Promise<void>;
+}
 export interface VerifyWebhookInput {
-    rawBody: string | Uint8Array;
-    headers: Headers | Record<string, string | string[] | undefined>;
-    secret: string | readonly string[];
+    readonly rawBody: string | Uint8Array;
+    readonly headers: Headers | Record<string, string | ReadonlyArray<string> | undefined>;
+    readonly secret: string | ReadonlyArray<string>;
+    readonly replayStore?: WebhookReplayStore;
+    readonly now?: number | Date;
+    readonly timestampToleranceSeconds?: number;
 }
-/**
- * Strip the `dalp_whsk_` family prefix from a DALP signing secret.
- *
- * The Standard Webhooks library expects the bare secret material; DALP
- * adds the prefix for parity with the `sm_dalp_` API-key family. Both
- * the dispatcher (DALP-side) and any verifier (DALP or consumer) must
- * call this before constructing a `new Webhook(...)` instance, otherwise
- * the HMAC inputs differ on the two ends and every signature mismatches.
- */
 export declare function toStandardWebhookSecret(secret: string): string;
-/**
- * Verifies a DALP webhook signature and returns the typed event union.
- *
- * Use the returned lifecycle state and `supersedes` accessor to reconcile
- * cached DAPI mutation responses with later on-chain outcomes.
- *
- * @see ../../kit/docs/content/events/idempotency-and-on-chain-outcome.mdx
- */
-export declare function verifyWebhook({ rawBody, headers, secret }: VerifyWebhookInput): WebhookVerificationResult;
-//# sourceMappingURL=verify-webhook.d.ts.map
+export declare function verifyWebhook(input: VerifyWebhookInput): Promise<WebhookVerificationResult>;

package/dist/verify-webhook.js

@@ -0,0 +1,8 @@
+import {
+  toStandardWebhookSecret2,
+  verifyWebhook2
+} from "./chunk-g5j1xky8.js";
+export {
+  toStandardWebhookSecret2 as toStandardWebhookSecret,
+  verifyWebhook2 as verifyWebhook
+};

package/dist/version.d.ts

@@ -1,5 +1,2 @@
-/** Semver version of the published SDK package. */
 export declare const SDK_VERSION: string;
-/** Default User-Agent header sent with every SDK request. */
 export declare const SDK_USER_AGENT: string;
-//# sourceMappingURL=version.d.ts.map

package/dist/wait-for-transaction.d.ts

@@ -1,94 +1,54 @@
-/**
- * Bounded wait-until-terminal barrier for queued DALP mutations.
- *
- * A v2 mutation may return a `202`-style async-accepted envelope when its
- * synchronous wait window elapses while the execution workflow is still
- * confirming. `waitForTransaction` turns that into a deterministic outcome:
- * poll the transaction status route at a FIXED interval bounded by a wall-clock
- * deadline, resolve on a terminal success, throw a typed error on a terminal
- * failure, and throw a loud timeout error if the deadline elapses first.
- *
- * This is a determinism barrier, not a masking retry — total wait is bounded by
- * `timeoutMs` (never exponential), and a never-terminating transaction fails
- * loud and bounded instead of hanging.
- *
- * Related: kit/sdk/src/types.ts
- * Related: packages/dalp/api-contract/src/routes/transaction/routes/transaction.status.schema.ts
- *
- * @module
- */
-import type { DalpClient } from "./types.js";
-/** Outcome shape returned by the transaction status route, narrowed to the fields this helper reads. */
-export interface WaitForTransactionResult {
-    readonly tokenAddress?: unknown;
+import type { DalpClient } from "./proxy/client.ts";
+import type { EvmTransactionStatusOutput } from "./generated/api-types.ts";
+export interface WaitForTransactionContractError {
+    readonly id: string;
+    readonly args: Readonly<Record<string, string>>;
+    readonly why: string;
+    readonly message: string;
+    readonly fix?: string;
 }
 export interface WaitForTransactionStatus {
-    transactionId: string;
-    status: string;
-    subStatus: string | null;
-    transactionHash: string | null;
-    errorMessage: string | null;
-    result?: WaitForTransactionResult;
+    readonly transactionId: string;
+    readonly status: string;
+    readonly subStatus: string | null;
+    readonly transactionHash: string | null;
+    readonly blockNumber?: string | null;
+    readonly errorMessage: string | null;
+    readonly contractError?: WaitForTransactionContractError | null;
+    readonly result?: WaitForTransactionResult;
+    readonly activeRequirement?: EvmTransactionStatusOutput["activeRequirement"];
+    readonly activeRequirementUnavailable?: EvmTransactionStatusOutput["activeRequirementUnavailable"];
+    readonly indexerRebuild?: EvmTransactionStatusOutput["indexerRebuild"];
+    readonly indexerRebuildUnavailable?: EvmTransactionStatusOutput["indexerRebuildUnavailable"];
+    readonly mayStillLand?: EvmTransactionStatusOutput["mayStillLand"];
+}
+export type WaitForTransactionResult = NonNullable<EvmTransactionStatusOutput["result"]>;
+export interface WaitForTransactionSuccess extends WaitForTransactionStatus {
+    readonly status: "COMPLETED";
 }
 export interface WaitForTransactionOptions {
-    /** Wall-clock ceiling for the whole wait, in milliseconds. Default 120_000. */
-    timeoutMs?: number;
-    /** Fixed delay between status polls, in milliseconds. Default 2_000. */
-    intervalMs?: number;
-    /**
-     * Resolve (instead of continuing to poll) when the transaction reaches
-     * `PENDING_APPROVAL` — an external approval gate (DFNS / Fireblocks) that is
-     * not a stall and may legitimately outlast the deadline. Default `true`.
-     */
-    resolveOnPendingApproval?: boolean;
-    /**
-     * Cancels the wait when the owning context (React component, request handler,
-     * workflow step) is torn down. An aborted signal stops the loop on the next
-     * iteration, cancels the in-flight status request, and surfaces as a
-     * {@link DalpTransactionWaitError} with `reason: "aborted"`.
-     */
-    signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly pollIntervalMs?: number;
+    readonly signal?: AbortSignal;
+    readonly onStatus?: (status: WaitForTransactionStatus) => void;
+    readonly holdWhilePaused?: boolean;
+    readonly holdWhileRebuilding?: boolean;
+    readonly now?: () => number;
+    readonly sleep?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+    readonly readStatus?: (transactionId: string, signal?: AbortSignal) => Promise<WaitForTransactionStatus>;
 }
-/**
- * Thrown when a transaction reaches a terminal failure state
- * (`FAILED` / `DEAD_LETTER` / `CANCELLED`), does not reach any terminal state
- * within the deadline (`reason: "timeout"`), or the caller's `AbortSignal`
- * fires (`reason: "aborted"`).
- */
+export type TransactionWaitFailureReason = "terminal-failure" | "timeout" | "aborted" | "funding-paused" | "indexer-rebuild";
 export declare class DalpTransactionWaitError extends Error {
+    readonly code = "sdk.transaction.WAIT_FAILED";
+    readonly category: "operational";
     readonly transactionId: string;
-    readonly status: string;
-    readonly subStatus: string | null;
-    readonly reason: "terminal-failure" | "timeout" | "aborted";
-    readonly lastStatus: WaitForTransactionStatus | undefined;
-    constructor(options: {
-        message: string;
-        transactionId: string;
-        status: string;
-        subStatus: string | null;
-        reason: "terminal-failure" | "timeout" | "aborted";
-        lastStatus?: WaitForTransactionStatus;
-        cause?: unknown;
-    });
+    readonly reason: TransactionWaitFailureReason;
+    readonly lastStatus?: WaitForTransactionStatus;
+    readonly elapsedMs?: number;
+    constructor(transactionId: string, reason: TransactionWaitFailureReason, lastStatus?: WaitForTransactionStatus, elapsedMs?: number);
+    get status(): string;
+    get subStatus(): string | null;
+    get retryable(): boolean;
 }
-/**
- * Poll the transaction status route until the transaction reaches a terminal
- * state or the deadline elapses.
- *
- * - `COMPLETED` → resolves with the final status (the handler already waited for
- *   the indexer drain, so this is a true read-after-write guarantee).
- * - `FAILED` / `DEAD_LETTER` / `CANCELLED` → throws {@link DalpTransactionWaitError}
- *   (`reason: "terminal-failure"`) carrying `status`, `subStatus`, and
- *   `errorMessage` — fail fast, do not keep polling.
- * - `PENDING_APPROVAL` → resolves as pending (when `resolveOnPendingApproval`,
- *   the default) so an external approval gate is never treated as a stall.
- * - deadline elapsed → throws {@link DalpTransactionWaitError} (`reason: "timeout"`)
- *   carrying the last observed status — a loud, bounded failure, never an
- *   indefinite hang.
- *
- * @param client A DALP API client.
- * @param transactionId The queue transaction identifier (UUIDv7) returned in the
- *   async-accepted envelope.
- */
-export declare function waitForTransaction(client: DalpClient, transactionId: string, options?: WaitForTransactionOptions): Promise<WaitForTransactionStatus>;
-//# sourceMappingURL=wait-for-transaction.d.ts.map
+export declare const isDalpTransactionWaitError: (error: unknown) => error is DalpTransactionWaitError;
+export declare function waitForTransaction(client: DalpClient, transactionId: string, options?: WaitForTransactionOptions): Promise<WaitForTransactionSuccess>;