@lumenwipe/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,577 @@
+export declare interface AccountSigner {
+    key: string;
+    weight: number;
+    type: "ed25519_public_key" | "hash_x" | "preauth_tx" | "ed25519_signed_payload";
+}
+
+export declare interface AccountState {
+    address: string;
+    network: Network;
+    sequence: string;
+    nativeBalanceLumens: string;
+    dataEntries: DataEntry[];
+    signers: AccountSigner[];
+    thresholds: AccountThresholds;
+    numSubEntries: number;
+    numSponsoring: number;
+    /** Ledger entries this account currently sponsors (on other accounts, or itself via a
+     *  fully-sponsored account creation). Populated by replaying sponsorship-relevant
+     *  operations and re-verifying each candidate's live sponsor - see sponsorship.ts. */
+    sponsoredEntries: SponsoredEntry[];
+    /** True when sponsoredEntries could not be enumerated completely (pagination cut off,
+     *  a live re-verification fetch failed, or the enumerated count doesn't match
+     *  numSponsoring). Mirrors subEntryMismatch: an incomplete read must never be treated
+     *  as "sponsors nothing" downstream. */
+    sponsorshipEnumerationIncomplete: boolean;
+    /** Account whose reserve covers this account's base reserve, or null. Populated by the
+     *  Horizon-based scan path only; the RPC getLedgerEntries response strips the outer
+     *  LedgerEntry extension where sponsoringID lives, so it remains null on that path. */
+    sponsoredBy: string | null;
+    /** AUTH_IMMUTABLE flag is set - ACCOUNT_MERGE is permanently blocked. */
+    authImmutable: boolean;
+    trustlines: Trustline[];
+    openOffers: OpenOffer[];
+    poolShares: PoolShareEntry[];
+    /** Claimable balances where this account is listed as a claimant. Does not affect
+     *  numSubEntries on this account; populated via the Horizon adapter. */
+    claimableBalances: ClaimableBalance[];
+    subEntryMismatch: boolean;
+}
+
+export declare interface AccountThresholds {
+    low: number;
+    med: number;
+    high: number;
+}
+
+export declare type ApiErrorBody = StructuredApiError | PlainApiError;
+
+/**
+ * What happens to a non-XLM balance before its trustline is removed.
+ *
+ * `convert` swaps it to XLM and `issuer` sends it back to be burned - both end the close with the
+ * position destroyed. `transfer` keeps the asset, as the asset, by paying it to another account
+ * that already holds the trustline.
+ */
+export declare type AssetDisposition = "convert" | "issuer" | "transfer";
+
+export declare interface BuildPlanResult {
+    steps: PlannedStep[];
+    blockers: PlanBlocker[];
+}
+
+export declare interface ClaimableBalance {
+    /** Full 72-char hex balance ID as returned by Horizon ("00000000" + 64-char hash). */
+    id: string;
+    /** "CODE:ISSUER" or "native" */
+    asset: string;
+    amount: string;
+    /** One entry per claimant on the balance, each with its own predicate. */
+    claimants: {
+        destination: string;
+        predicate: ClaimPredicate;
+    }[];
+    /** Account sponsoring this balance's reserve, or null if unsponsored. */
+    sponsor: string | null;
+}
+
+export declare type ClaimableBalanceSelection = "claim" | "add_trustline_then_claim" | "forfeit";
+
+export declare type ClaimPredicate = {
+    type: "unconditional";
+} | {
+    type: "and";
+    predicates: ClaimPredicate[];
+} | {
+    type: "or";
+    predicates: ClaimPredicate[];
+} | {
+    type: "not";
+    predicate: ClaimPredicate;
+} | {
+    type: "before_absolute_time";
+    absBeforeEpoch: string;
+} | {
+    type: "before_relative_time";
+    relBeforeSeconds: string;
+    deadlineEpoch: string;
+};
+
+export declare type CloseApiStatus = "ready" | "needs_decisions" | "blocked" | "complete";
+
+export declare interface CloseEngineDeps {
+    /** Fetches the next round of unsigned transactions from the API (via the proxy). */
+    getTransactions: () => Promise<TransactionsResponse>;
+    /**
+     * Verifies one server-built transaction against what the client independently expects.
+     * MUST throw on any mismatch. This is the trust anchor: the browser never signs a
+     * server-built transaction it cannot fully account for. Injected so it can be tested in
+     * isolation; the hook supplies the real `verifyCloseTransaction`.
+     * May be sync or async - the engine always awaits it, so a future async verifier
+     * (e.g. one that resolves a key or does a lookup) can never be silently bypassed.
+     */
+    verify: (tx: CloseTransaction) => void | Promise<void>;
+    /** The signing weight this transaction actually needs, from its operation set and the
+     *  account's real per-category thresholds - never a single account-wide number. */
+    requiredWeight: (tx: CloseTransaction) => number;
+    /** Signs the given xdr (which may already carry earlier signatures) with the currently
+     *  available signer, returning the updated xdr and its total accumulated signing weight
+     *  against the account's known signer set. */
+    sign: (tx: CloseTransaction, xdr: string) => Promise<{
+        xdr: string;
+        weight: number;
+    }>;
+    /** Submits a transaction whose accumulated weight already meets its requirement; resolves
+     *  to the tx hash. */
+    submit: (tx: CloseTransaction, xdr: string) => Promise<string>;
+    /** Called after a transaction confirms, with the transaction and its hash. */
+    onConfirmed?: (tx: CloseTransaction, hash: string) => void;
+    onProgress?: (message: string) => void;
+    /** Safety bound so a misbehaving API can never spin the loop forever. */
+    maxRounds?: number;
+}
+
+/** Body for `POST /v1/:network/close/plan`. */
+export declare interface ClosePlanRequest {
+    source: string;
+    destination?: string;
+    decisions?: DecisionAnswer[];
+}
+
+export declare interface CloseTransaction {
+    id: string;
+    order: number;
+    dependsOn: string[];
+    xdr: string;
+    networkPassphrase: string;
+    sourceSequence: string;
+    validUntilLedger: number;
+    covers: StepType[];
+    intent: TxIntent;
+}
+
+/** Body for `POST /v1/:network/close/transactions`. */
+export declare interface CloseTransactionsRequest {
+    source: string;
+    destination: string;
+    decisions?: DecisionAnswer[];
+    /**
+     * Deposit memo value for exchange destinations that require one. The memo type
+     * is taken from the exchange registry, not the client. Required when the
+     * destination is an exchange that mandates a memo.
+     */
+    memo?: string;
+}
+
+export declare interface ConversionPath {
+    fromAsset: string;
+    toAsset: string;
+    path: string[];
+    estimatedReceive: string;
+    destMin: string;
+}
+
+export declare interface DataEntry {
+    key: string;
+    value: string;
+}
+
+export declare interface DecisionAnswer {
+    id: string;
+    choice: string;
+    params?: {
+        maxSlippageBps?: number;
+        /**
+         * Required by the `transfer_to_account` choice: the `G...` address the balance is paid to.
+         *
+         * It travels with the answer rather than in a separate map so a destination cannot become
+         * detached from the asset it was chosen for - the same reason the unrecognized-destination
+         * acknowledgement is keyed by address instead of being a boolean. A `transfer_to_account`
+         * answer without a valid destination is a 422; there is no default, because every available
+         * fallback would destroy the balance the user asked to keep.
+         */
+        destination?: string;
+    };
+}
+
+export declare interface DecisionOption {
+    id: string;
+    recommended?: boolean;
+    quote?: QuoteInfo;
+    note?: string;
+}
+
+export declare interface DecisionPoint {
+    id: string;
+    type: "asset_disposition" | "confirmation" | "choice" | "claimable_balance";
+    subject: Record<string, unknown>;
+    options: DecisionOption[];
+    default: string;
+    required: boolean;
+}
+
+export declare type DemolishPhase = "IDLE" | "ANALYZING" | "PREFLIGHT_COMPLETE" | "SIGNER_SETUP" | "STEP_EXECUTING" | "STEP_CONFIRMED" | "STEP_FAILED" | "COMPLETE" | "ABORTED";
+
+export declare interface ExecutionTxBreakdown {
+    order: number;
+    covers: StepType[];
+    reason?: "op_batch" | "defi_dependency";
+}
+
+export declare type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+/** Response from `GET /health`. */
+export declare interface HealthResponse {
+    status: string;
+}
+
+/** Thrown when a transaction's accumulated signing weight is still short of what it actually
+ *  needs after the currently available signer has contributed. Carries everything needed to
+ *  resume with a different signer onto the same partially-signed envelope. */
+export declare class InsufficientSignatureWeightError extends Error {
+    readonly pending: PendingRound;
+    constructor(pending: PendingRound);
+}
+
+/**
+ * One operation in a decoded close transaction.
+ *
+ * `source` is the account the operation acts as - the operation's own source account when it
+ * carries one, otherwise the transaction's. It is what lets verification assert relationships
+ * *between* operations rather than trusting each in isolation: in a mediated close the forward
+ * payment must be sent by the very account the merge just paid into, which is what makes the
+ * intermediary a conduit rather than a destination. Without it the only available check is
+ * pinning the intermediary's address, which every consumer would then have to be told.
+ */
+export declare type IntentOperation = IntentOperationBody & {
+    source: string;
+};
+
+export declare type IntentOperationBody = {
+    type: "path_payment_strict_send";
+    sendAsset: string;
+    sendAmount: string;
+    destination: string;
+    destAsset: string;
+    destMin: string;
+    path: string[];
+} | {
+    type: "payment";
+    destination: string;
+    asset: string;
+    amount: string;
+} | {
+    type: "change_trust";
+    asset: string;
+    limit: string;
+} | {
+    type: "account_merge";
+    destination: string;
+} | {
+    type: "manage_sell_offer";
+    offerId: string;
+    amount: string;
+} | {
+    type: "manage_data";
+    name: string;
+    value: string | null;
+} | {
+    type: "set_options";
+    signer: AccountSigner | null;
+    masterWeight: number | null;
+    lowThreshold: number | null;
+    medThreshold: number | null;
+    highThreshold: number | null;
+    homeDomain: string | null;
+    setFlags: number | null;
+    clearFlags: number | null;
+    inflationDest: string | null;
+} | {
+    type: "claim_claimable_balance";
+    balanceId: string;
+} | {
+    type: "revoke_sponsorship";
+    entryKind: "account" | "trustline" | "offer" | "data_entry" | "signer";
+    owner: string;
+} | {
+    type: "unknown";
+};
+
+/** Thrown when the API responds with a non-2xx status. `body` is the parsed error payload. */
+export declare class LumenWipeApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown);
+}
+
+/**
+ * Thin, typed client over the LumenWipe REST API. It only relays JSON and XDR
+ * strings - transaction building and signing stay with the caller, so this
+ * package has no `@stellar/stellar-sdk` dependency.
+ */
+export declare class LumenWipeClient {
+    private readonly http;
+    private readonly defaultNetwork;
+    constructor(options: LumenWipeClientOptions);
+    health(): Promise<HealthResponse>;
+    getAccount(address: string, network?: Network): Promise<AccountState>;
+    getPaths(params: {
+        fromAsset: string;
+        amount: string;
+    }, network?: Network): Promise<PathResponse>;
+    closePlan(body: ClosePlanRequest, network?: Network): Promise<PlanResponse>;
+    /**
+     * Builds the next unsigned transaction(s) for a close. A close can span several
+     * transactions (a fused close, or separate claim / cleanup / mediator-merge steps),
+     * so the response's `remaining.requiresAnotherCall` says whether more follow: sign and
+     * submit the returned transactions in `order`, wait for confirmation, then call this
+     * again until `requiresAnotherCall` is false.
+     */
+    closeTransactions(body: CloseTransactionsRequest, network?: Network): Promise<TransactionsResponse>;
+    submit(signedXdr: string, network?: Network): Promise<SubmitResponse>;
+    mediatorCheck(address: string, network?: Network): Promise<MediatorCheckResult>;
+    mediatorSign(transaction: string, network?: Network): Promise<MediatorSignResponse>;
+}
+
+export declare interface LumenWipeClientOptions {
+    /** Base URL of the LumenWipe API, e.g. `https://api.lumenwipe.com`. */
+    baseUrl: string;
+    /** Integrator API key, sent as `Authorization: Bearer <apiKey>`. */
+    apiKey: string;
+    /** Default network for calls that omit it. Defaults to `"testnet"`. */
+    network?: Network;
+    /** Custom fetch (for environments without a global `fetch`, or for testing). */
+    fetch?: FetchLike;
+    /** Per-request timeout in milliseconds. Defaults to 30000. `0`/`Infinity` disables it. */
+    timeout?: number;
+}
+
+/** Thrown when a request exceeds the configured timeout. */
+export declare class LumenWipeTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+
+export declare interface MediatorCheckResult {
+    requiresMediator: boolean;
+    reason: string;
+    requiresMemo: boolean;
+    memoType: "text" | "id" | "hash" | null;
+    exchangeName: string | null;
+    /** Whether the server can actually perform the mediator flow (secret configured). */
+    available: boolean;
+}
+
+/** Response from `POST /:network/mediator/sign`. */
+export declare interface MediatorSignResponse {
+    transaction: string;
+}
+
+export declare type Network = "mainnet" | "testnet";
+
+export declare interface OpenOffer {
+    id: string;
+    selling: string;
+    buying: string;
+    amount: string;
+    price: string;
+}
+
+/** Response from `GET /:network/paths`. */
+export declare interface PathResponse {
+    path: ConversionPath | null;
+}
+
+/** Everything needed to resume signing a transaction that stopped short of its required
+ *  signing weight, without re-fetching (which would discard any signature already
+ *  collected) or re-verifying (the tx body is unchanged - verified once, before the first
+ *  signature; a later signer only adds a signature, never alters the body). */
+export declare interface PendingRound {
+    tx: CloseTransaction;
+    xdr: string;
+    requiredWeight: number;
+    accumulatedWeight: number;
+    queue: CloseTransaction[];
+    requiresAnotherCall: boolean;
+}
+
+/** @deprecated The API emits one envelope (`StructuredApiError`). Kept only so a consumer
+ *  pinned to an older deployment still type-checks during a rollout; remove once none remain. */
+export declare interface PlainApiError {
+    error: string;
+}
+
+export declare interface PlanBlocker {
+    message: string;
+    helpUrl?: string;
+    /** Distinguishes an acknowledged, non-trapping warning (e.g. a chosen forfeit) from a hard
+     *  blocker. Absent means the generic hard-blocking case. */
+    code?: string;
+}
+
+export declare interface PlannedStep {
+    index: number;
+    type: StepType;
+    title: string;
+    description: string;
+    operationCount: number;
+    estimatedFeeLumens: string;
+    txXdr: string | null;
+    status: StepStatus;
+    txHash: string | null;
+    error: string | null;
+    affectedAsset?: string;
+    fallbackToIssuer?: boolean;
+}
+
+export declare interface PlanResponse {
+    planHash: string;
+    status: CloseApiStatus;
+    steps: unknown[];
+    decisionPoints: DecisionPoint[];
+    blockers: {
+        code: string;
+        message: string;
+        helpUrl?: string;
+    }[];
+    estimate: {
+        feeStroops: string;
+        freedReserveXlm: string;
+    };
+    execution: {
+        estimatedTransactionCount: number;
+        transactions: ExecutionTxBreakdown[];
+    };
+}
+
+export declare interface PoolShareEntry {
+    poolId: string;
+}
+
+export declare interface QuoteInfo {
+    estimatedReceive: string;
+    path: string[];
+    source: "soroswap" | "sdex";
+    expiresAtLedger: number;
+}
+
+/**
+ * Runs the full multi-round close. Each round: fetch a batch of unsigned transactions,
+ * verify every one before signing, sign it, and submit only once its accumulated signing
+ * weight meets what its operations actually require - otherwise throw
+ * InsufficientSignatureWeightError with everything needed to resume onto the same
+ * envelope once a different signer is available. Pass that error's `.pending` back in as
+ * `resume` to continue exactly where it stopped.
+ */
+export declare function runClose(deps: CloseEngineDeps, resume?: PendingRound): Promise<void>;
+
+/**
+ * A ledger entry this account currently sponsors, on another account (or itself, for
+ * "account" - a fully-sponsored account creation). Mirrors the ledger-key kinds
+ * RevokeSponsorship supports. Claimable balances have no owning-account concept in
+ * their ledger key (unlike the other five kinds), so they carry only balanceId.
+ */
+export declare type SponsoredEntry = {
+    kind: "account";
+    owner: string;
+} | {
+    kind: "trustline";
+    owner: string;
+    asset: string;
+} | {
+    kind: "offer";
+    owner: string;
+    offerId: string;
+} | {
+    kind: "data_entry";
+    owner: string;
+    name: string;
+} | {
+    kind: "signer";
+    owner: string;
+    signerKey: string;
+} | {
+    kind: "claimable_balance";
+    balanceId: string;
+};
+
+export declare type StepStatus = "pending" | "signing" | "submitted" | "confirmed" | "failed" | "skipped";
+
+export declare type StepType = "NORMALIZE_SIGNERS" | "REVOKE_SPONSORSHIP" | "REMOVE_DATA_ENTRIES" | "CANCEL_OFFERS" | "ADD_TRUSTLINE_FOR_CLAIM" | "CLAIM_BALANCES" | "HANDLE_ASSETS" | "REMOVE_TRUSTLINES" | "CLOSE_ACCOUNT" | "MERGE";
+
+/** Structured error body used by the v1 (`/v1/...`) endpoints. */
+export declare interface StructuredApiError {
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+
+/** Body for `POST /v1/:network/submit`. */
+export declare interface SubmitRequest {
+    signedXdr: string;
+}
+
+/** Response from `POST /v1/:network/submit`. */
+export declare interface SubmitResponse {
+    status: "success";
+    hash: string;
+    ledger: number;
+}
+
+export declare interface TransactionsResponse {
+    planHash: string;
+    status: CloseApiStatus;
+    transactions: CloseTransaction[];
+    /**
+     * `requiresAnotherCall` is true when more transactions follow the returned batch:
+     * submit these, wait for confirmation, then request transactions again. `steps` is the
+     * approximate number of build rounds still remaining.
+     */
+    remaining: {
+        steps: number;
+        requiresAnotherCall: boolean;
+    };
+}
+
+/**
+ * Where a `transfer` disposition sends its balance, keyed by the same canonical `CODE:ISSUER`
+ * string the disposition itself is keyed by.
+ *
+ * Per asset and arbitrary: the API takes any address here, independently for each asset. Offering
+ * "the same account you are merging into" is a UI convenience, not a constraint of the contract -
+ * an SDK consumer can send each asset somewhere different.
+ *
+ * There is deliberately no amount. The `ChangeTrust` that removes the trustline runs immediately
+ * after and fails on a non-zero balance, so anything short of the full balance would strand the
+ * close midway.
+ */
+export declare type TransferDestinations = Record<string, string>;
+
+export declare interface Trustline {
+    asset: string;
+    balance: string;
+    limit?: string;
+    authorized: boolean;
+    issuer: string;
+    code: string;
+}
+
+export declare interface TxIntent {
+    summary: string;
+    source: string;
+    fee: string;
+    memo: string | null;
+    /** The memo's type, so a check can assert it matches what the destination requires rather
+     *  than only that some memo is present. */
+    memoType: "text" | "id" | "hash" | null;
+    guarantees: {
+        mergeDestination: string | null;
+        paymentsOnlyTo: string[];
+        minXlmFromConversions: string | null;
+    };
+    operations: IntentOperation[];
+}
+
+export { }