@chironbuilder/ootle-sdk 0.1.0

package/dist/wallet.d.ts

@@ -0,0 +1,733 @@
+import { Network } from "@tari-project/ootle";
+import type { ExecuteResult, IndexerGetTransactionResultResponse, Instruction, SubstateRequirement, TransactionId } from "@tari-project/ootle-ts-bindings";
+import { IndexerProvider } from "@tari-project/ootle-indexer";
+import { SecretKeyWallet } from "@tari-project/ootle-secret-key-wallet";
+import type { WalletAccountApi } from "./accountApi";
+import type { ScannedStealthOutput } from "./confidential";
+import { type NetworkName } from "./ootleNetwork";
+import type { ShieldedOutputRecord } from "./storage";
+export interface TokenBalance {
+    resourceAddress: string;
+    kind: string;
+    /** The plain, public (revealed) amount — what this vault shows on-chain to anyone. */
+    amount: bigint;
+    /** Value hidden inside this vault's Pedersen commitments, decrypted with this account's own
+     * view key (see confidential.ts) — 0n for every kind except Confidential, and for a
+     * Confidential vault with no commitments. Never requires a network call beyond what
+     * getBalances() already fetches. */
+    confidentialAmount: bigint;
+    /** Commitments that failed to decrypt against this account's view key. Expected to be 0 for a
+     * vault's own commitments map (every entry there should be ours) — nonzero is worth surfacing,
+     * not silently swallowing. */
+    confidentialDecryptFailures: number;
+    /** The resource's on-chain decimal precision (e.g. 6 for XTR, 8 for a typical DemoToken) —
+     * a real `Resource.divisibility` field, not a guessed convention. */
+    divisibility: number;
+    /** The resource's `metadata.SYMBOL`, if it set one — null for a resource with no such metadata
+     * key, in which case a caller should fall back to the address. */
+    symbol: string | null;
+    /** The resource's `metadata.name` (a longer display name, distinct from the ticker-style
+     * `symbol`), if it set one — null otherwise. */
+    name: string | null;
+    /** Token IDs held in this vault, for a `NonFungible` resource only — null for every other kind.
+     * A NonFungible vault's container has no `.amount`/`.revealed_amount` field at all (only
+     * `token_ids`/`locked_token_ids`), so `amount` above is synthesized as this array's length. */
+    nonFungibleTokenIds: string[] | null;
+}
+/** One resource's total unspent *stealth* holding -- `OotleAccount.getPrivateBalances()`'s element
+ * type. Deliberately separate from `TokenBalance`: that describes a vault (public amount plus any
+ * decrypted commitments), this describes a set of freestanding stealth UTXOs, and a resource can
+ * have either, both, or only the latter. */
+export interface PrivateBalance {
+    resourceAddress: string;
+    /** Sum of the unspent outputs' amounts, raw resource-native units (same convention as
+     * `TokenBalance.amount`). */
+    amount: bigint;
+    /** How many unspent outputs make up `amount`. Each is spent whole, so this bounds what a single
+     * spend can be covered by -- see `resolveUnshieldPlan`'s coin selection. */
+    outputCount: number;
+    divisibility: number;
+    symbol: string | null;
+    name: string | null;
+}
+/**
+ * A stealth output's **minimum value promise**: a public claim, committed into the output's own
+ * range proof, that it is worth at least this much.
+ *
+ * A confidential output normally carries a range proof for `0 <= v < 2^64`, hiding `v` completely.
+ * Set a promise `m` and the proof instead attests `m <= v < 2^64`, with `m` stored in the clear on
+ * the output (`UnspentOutput.minimum_value_promise`). Anyone reading the output on-chain learns
+ * "worth at least `m`" and nothing more precise -- which is exactly a proof of funds: a permanent,
+ * non-interactive, publicly verifiable artifact that needs no cooperation from this wallet to check
+ * (fetch the `utxo_{resource}_{commitment}` substate, read the field, confirm it is still unspent).
+ *
+ * Two things follow that callers must get right, which is why this is validated rather than passed
+ * straight through:
+ *
+ * 1. **A promise above the real value is unprovable.** The bulletproof asserting `m <= v` cannot be
+ *    generated when `m > v`, so this fails here with a message that says so, rather than deeper in
+ *    the wasm with something opaque -- or, worse, producing a proof the network then rejects after
+ *    the fee half of the transaction has already been committed.
+ * 2. **It is a permanent, irreversible privacy disclosure.** Shielding is how value stops being
+ *    publicly visible; a promise puts a floor back on public view, for the life of the output, for
+ *    everyone -- not just whoever the proof was made for. That is the deliberate trade being made,
+ *    and it is why every path reaching this asks the user first.
+ */
+export declare function assertValidMinimumValuePromise(promise: bigint, amount: bigint): void;
+/**
+ * One derived Ootle account: a signer (owner + view keypair) plus the network connection needed
+ * to read its state and submit transactions, entirely independent of the wallet daemon.
+ */
+export declare class OotleAccount implements WalletAccountApi {
+    readonly index: number;
+    readonly network: Network;
+    readonly signer: SecretKeyWallet;
+    private provider;
+    private readonly ownerSecret;
+    private constructor();
+    /** `entropy` is the 16-byte CipherSeed entropy (see cipherSeed.ts), not a raw 32-byte seed. */
+    static fromSeed(entropy: Uint8Array, index: number, networkName: NetworkName): OotleAccount;
+    getProvider(): Promise<IndexerProvider>;
+    /**
+     * The bech32m "otl_..." wallet address, for display / receiving funds. Confirmed (empirically,
+     * against `generateOotleAddress`) to be what `Signer.getAddress()` actually returns for a
+     * `SecretKeyWallet` — despite the base `Signer` interface's JSDoc calling it "the component
+     * address", it is NOT the on-chain account component address. See `getComponentAddress()`.
+     */
+    getWalletAddress(): Promise<string>;
+    getPublicKey(): Promise<Uint8Array>;
+    /**
+     * The account's on-chain component address — what instructions use as the `account` argument
+     * (deposit/withdraw/pay_fee/etc.) and what `getVaultIdsForAccount` needs to find balances.
+     *
+     * Computed client-side via `deriveAccountComponentAddress` (`componentAddress.ts`), which
+     * reproduces Ootle's domain-separated Blake2b hash of (ACCOUNT_TEMPLATE_ADDRESS, owner_public_key)
+     * byte-for-byte — verified against all three committed golden vectors from
+     * `tari-ootle`'s `crates/ootle_sdk_core/fixtures/address_derive/`.
+     */
+    getComponentAddress(): Promise<string>;
+    getBalances(): Promise<TokenBalance[]>;
+    /**
+     * Builds, signs (with this account's key) and submits/dry-runs a transaction. `opts.inputs` lets
+     * a caller pre-pin substates it already knows are needed; beyond that, this indexer requires
+     * *every* substate an instruction touches to be listed as an input — even ones referenced only
+     * by address in a `CallMethod` on an already-existing component (confirmed empirically, first
+     * with the faucet, and again with this account's own existing component when calling into it for
+     * a `pay_fee`/`deposit`/`withdraw` on a second use) — and there's no want-derivation pass in this
+     * TS SDK to discover that dependency graph up front the way the Rust `ootle_sdk_core` can.
+     *
+     * Rather than hand-tracing each call's full component/vault graph, this retries on the specific
+     * rejection the engine itself gives for a missing input — "At instruction #N: <address> not
+     * found" — extracting that address, resolving its current version, adding it to the pinned
+     * inputs, and resubmitting. Each retry can surface a *different* missing address (a component's
+     * vaults are only discoverable after the component itself is known), so this loops until either
+     * success or the same address reappears (nothing new left to resolve). The version-race retry
+     * `claimTestnetXtr()` needs for a heavily-contended shared substate is folded in too.
+     */
+    execute(instructions: Instruction[], opts?: {
+        maxFee?: bigint;
+        dryRun?: boolean;
+        inputs?: SubstateRequirement[];
+        maxRetries?: number;
+    }): Promise<{
+        transaction_id: TransactionId;
+        result: ExecuteResult;
+    } | IndexerGetTransactionResultResponse>;
+    /**
+     * A working replacement for the SDK's exported `sendDryRun()`, which is broken against this
+     * indexer: it builds the identical signed/sealed envelope but POSTs it to the regular
+     * `transactions` endpoint, which rejects dry-run envelopes with "Dry-run transactions must be
+     * submitted to the /transactions/dry-run endpoint" (confirmed empirically). This reproduces
+     * `sendDryRun`'s own pipeline — set `dry_run`, `resolveTransaction`, `signTransaction`,
+     * `sealTransaction` (all exported, same functions it uses internally) — but posts the sealed
+     * envelope to the correct path via the indexer client's transport directly. Dry-run responses
+     * come back synchronously with the full result already attached (no `transactions/{id}/result`
+     * polling needed, unlike a real submission).
+     *
+     * The response shape (`{transaction_id, result: ExecuteResult}`) is the indexer's own
+     * `SubmitTransactionDryRunResponse` (`applications/tari_indexer/src/rest_api/handlers/
+     * transactions.rs`'s `submit_transaction_dry_run` handler) — confirmed directly against that
+     * Rust source since `@tari-project/ootle-ts-bindings` doesn't export a matching type for it
+     * (only the real-submission response, which no longer carries a `result` field at all as of
+     * the 0.39.0 protocol upgrade).
+     */
+    private submitDryRun;
+    /**
+     * A working replacement for the SDK's exported `sendTransaction()`. That function still submits
+     * correctly, but its own polling (`ct()`/`st()` internally) only surfaces a generic
+     * `abort_details` summary on rejection — not the full structured `RejectReason`/`SubstateDiff`
+     * this class's auto-resolve retry (see `execute()`) needs to find a missing substate's address
+     * in. Confirmed empirically: a real submission that hit "SubstateNotFound: vault_... not found"
+     * came back from `sendTransaction()` with no address in the thrown message at all, so the retry
+     * loop had nothing to extract and gave up on the first attempt — the exact failure this method
+     * exists to fix. Submission itself (`provider.submitTransaction`) is unchanged and already
+     * proven correct; only the result-polling and error-message construction are reimplemented, in
+     * the same detailed shape `submitDryRun()` above already produces.
+     */
+    private submitReal;
+    /**
+     * Transfers `amount` (raw, resource-native units) of `resourceAddress` from this account to
+     * `recipientAddress` — a plain `withdraw` off this account's own vault, handed straight to
+     * `deposit` on the recipient's account component via a workspace bucket, in one transaction.
+     * Works for any resource this account holds, including XTR; `execute()`'s auto-resolve retry
+     * (see its own doc comment) discovers and pins whichever vaults/components aren't already
+     * known, exactly as it does for every other instruction this class builds by hand.
+     *
+     * `recipientAddress` accepts either form (see `WalletAccountApi.send`'s doc comment): the
+     * recipient's bech32m wallet address, or a bare `component_...` address. `CallMethod.call` is a
+     * `SubstateId`, so it must end up being the latter either way — handing an "otl_…" straight
+     * through is not a friendly error: `SubstateId::from_str` splits on the first underscore, does
+     * not recognise the `otl` prefix, and the instruction then fails to deserialize, surfacing from
+     * the wasm as "data did not match any variant of untagged enum TransactionInput", naming neither
+     * the field nor the reason.
+     *
+     * `deposit` is a method call on an *existing* component, and `CreateAccount` is create-or-conflict
+     * (against an account that already exists it rejects with "Substate <component>:0 is already UP
+     * and conflicts with an existing output" -- Tari's own walletd reads that exact string as "this
+     * already exists" in its faucet handler), so a brand-new recipient's account is created only when
+     * it is genuinely missing, and only when a wallet address was given -- a bare component address
+     * never reveals the owner key `CreateAccount` needs, so that form can only pay an account that
+     * already exists.
+     */
+    send(recipientAddress: string, resourceAddress: string, amount: bigint, maxFee?: bigint): Promise<{
+        transaction_id: TransactionId;
+        result: ExecuteResult;
+    } | IndexerGetTransactionResultResponse>;
+    /**
+     * Moves `amount` of this account's own REVEALED balance into a Confidential-type vault for the
+     * same resource -- the "Confidential" `ResourceType`'s equivalent of `shield()`, a different
+     * privacy mechanism from Stealth (vault-based, ElGamal-encrypted to a resource view key, rather
+     * than freestanding one-time-key UTXOs -- see the resource-types write-up in the integration
+     * docs). Only meaningful for a resource actually created as `ResourceType::Confidential`; calling
+     * this against a Fungible or Stealth resource's vault fails on-chain ("resource type mismatch" or
+     * similar), not client-side -- this class has no way to know a resource's type up front without
+     * an extra substate fetch, so the failure is left to the engine.
+     *
+     * Builds a `ConfidentialWithdrawProof` client-side (no wallet-daemon round trip) via the vendored
+     * `createConfidentialWithdrawProofLiteral` -- see that WASM export's own doc comment for why the
+     * `tari_bor` encoding happens in Rust rather than being hand-rolled here: the official
+     * `@tari-project/ootle` SDK's own `feeTransactionPayFromComponentConfidential` is unimplemented
+     * for exactly this reason ("a ConfidentialWithdrawProof Literal must be tari_bor-CBOR-encoded,
+     * which the TS SDK does not yet support").
+     *
+     * The new confidential output is addressed to this account's own owner/view keys -- the same
+     * one-time-output-witness construction `createStealthOutputWitness` already builds for Stealth
+     * outputs, reused here since `ConfidentialOutputStatement.output` and a `StealthOutputWitness`'s
+     * `witness` share the exact same shape (mask, sender_public_nonce, encrypted_data). Only the
+     * `witness` half of that result is used -- the `auth`/`tag` halves are Stealth-specific
+     * (`SpendAuthorization`/`UtxoTag`); a Confidential output has neither, ownership being purely
+     * "which vault holds it," not a spend-authorization key.
+     *
+     * Two instructions, mirroring `send()`'s withdraw-then-deposit shape: `withdraw_confidential`
+     * (drawing `amount` from the vault's revealed side, per the proof's `input_revealed_amount`)
+     * produces a bucket holding the one new confidential output, which `deposit` puts back in the
+     * same vault.
+     */
+    depositConfidential(resourceAddress: string, amount: bigint, maxFee?: bigint): Promise<{
+        transaction_id: TransactionId;
+        result: ExecuteResult;
+    } | IndexerGetTransactionResultResponse>;
+    /**
+     * Claims free testnet XTR from the network's builtin faucet (esmeralda/igor only — there is no
+     * such faucet on mainnet). Mirrors both `build_faucet_claim_with_wants` in tari-ootle's
+     * `crates/ootle_sdk_core/src/faucet.rs` and (confirmed against its actual pinned-input list)
+     * `handle_create_free_test_coins` in `applications/tari_walletd/src/handlers/accounts.rs` — the
+     * handler backing the `accounts.create_free_test_coins` walletd RPC that tari-dex's swap-ui
+     * calls. Self-funding, so it works even for a brand-new account that doesn't exist on-chain yet:
+     * the fee phase itself creates the account, funds it from the faucet
+     * (`XTR_FAUCET_COMPONENT_ADDRESS.take(account)`), then pays its own fee out of what it just
+     * received.
+     *
+     * Unlike every other component this class calls, none of the faucet's substates (component,
+     * vault, claim resource) get auto-resolved from the instructions by this indexer — each has to
+     * be pinned as an explicit transaction input (confirmed empirically: submitting with only the
+     * claim resource pinned rejected with "component_...0000 not found" at the `take` call).
+     * `provider.resolveInputs()` fills in each one's current version.
+     *
+     * The faucet vault is a single shared substate every claimant on the testnet contends for, so
+     * the version pinned by `resolveInputs()` routinely goes stale between resolution and consensus
+     * (confirmed empirically: "Lock failure: Substate vault_...:8 is DOWN" — someone else's claim
+     * landed first). This isn't a bug to fix, just contention to ride out: catch that specific
+     * rejection and retry with freshly-resolved versions and a new transaction id.
+     *
+     * Retries back off (`retryDelayMs * (attempt + 1)`, so 300ms, 600ms, 900ms, ...) rather than
+     * resubmitting back-to-back: confirmed empirically that hammering `resolveInputs()` immediately
+     * after a rejection can keep handing back the same already-stale version every time (the
+     * indexer's own view of a shared, heavily-contended substate can lag behind consensus by more
+     * than one round trip takes) — a short, growing pause gives that view time to catch up instead
+     * of burning the whole retry budget re-observing the same stale state.
+     */
+    claimTestnetXtr(maxFee?: bigint, retries?: number, retryDelayMs?: number): Promise<IndexerGetTransactionResultResponse>;
+    /**
+     * Shields (moves from revealed to private/confidential) `amount` of `resourceAddress`, held as
+     * a new stealth output owned by this same account. Uses an entirely separate submission
+     * pipeline from `execute()`: the SDK's `StealthTransfer` builder produces its own
+     * `TransactionEnvelope` directly (via `WalletStealthAuthorizer`/`AuthorizedTransfer`), not
+     * through `TransactionBuilder`/`resolveTransaction`/`signTransaction`/`sealTransaction`.
+     *
+     * The one genuinely new failure mode this adds beyond `send()`: if the extension's service
+     * worker is killed *after* the transaction finalizes on-chain but *before* the resulting
+     * commitment is written to storage, the shield succeeds financially but the wallet loses its
+     * only lead back to that output — worse than a failed `send()`, whose destination is always a
+     * known component address. `pendingShieldTransactionIds` (written before polling, cleared only
+     * after the commitment record is stored) narrows that window to "killed between finalization
+     * and one storage write" and gives `recoverPendingShields()` (background/index.ts) something
+     * to reconcile on next launch.
+     *
+     * `maxFee` defaults far higher than `send()`'s 5000 -- confirmed live that 5000 gets
+     * "AcceptFeeRejectRest" with `ExecutionFailure: "Insufficient fees to fund native
+     * verification"` (the stealth balance proof / range proof verification costs real compute
+     * points beyond the engine's free grace allowance). Unused fee is refunded on success, so
+     * erring high just wastes nothing; erring low burns the small fee-intent cost with nothing to
+     * show for it, since only the fee half of the transaction gets committed.
+     */
+    shield(resourceAddress: string, amount: bigint, maxFee?: bigint, memo?: string, minimumValuePromise?: bigint): Promise<{
+        transactionId: string;
+        commitment: string;
+        substateId: string;
+        minimumValuePromise: string;
+    }>;
+    /**
+     * Proves this account currently controls the stealth output at `substateId` -- e.g. a
+     * `minimumValuePromise` proof-of-funds output this account created earlier -- by Schnorr-signing
+     * `challenge` with the output's one-time spend key. Spends nothing and reveals nothing about the
+     * output beyond what `tari_getSubstate` already shows anyone.
+     *
+     * `challenge` is signed under a domain tag (`ownershipProof.ts`) disjoint from real transaction
+     * signing, so the resulting signature can never be replayed as spend authorization for this or
+     * any other output -- this is the entire reason a caller cannot just ask for a raw signature over
+     * an arbitrary message.
+     *
+     * Throws if the substate isn't a live, key-authorized stealth output, or if it isn't actually
+     * addressed to this account (checked by re-deriving the expected one-time public key and
+     * comparing it to the substate's own `auth.Key` -- the same check `scan_stealth_output` does
+     * receiver-side, just run here against a specific caller-supplied id instead of a scan).
+     */
+    signOwnershipProof(resourceAddress: string, substateId: string, challenge: string): Promise<{
+        publicKey: string;
+        publicNonce: string;
+        signature: string;
+    }>;
+    /**
+     * Proves this account holds a specific `otl_…` wallet address by Schnorr-signing `challenge`
+     * with the account's own persistent owner key -- not a per-output derived one, so unlike
+     * `signOwnershipProof` this needs no substate lookup and isn't tied to any particular output.
+     *
+     * Signs under a domain tag (`ownershipProof.ts`) disjoint from real transaction signing, for the
+     * same reason `signOwnershipProof` does: this exact key also signs real transactions
+     * (`SecretKeyWallet.signTransaction`), so a raw signature over caller-supplied bytes would risk
+     * being replayable as spend authorization.
+     *
+     * A verifier checks the result against the owner key decoded from the wallet address *they*
+     * already have in mind (`parseOotleAddress`) -- never against a value this call's caller reports
+     * about themselves.
+     */
+    signWalletOwnership(challenge: string): Promise<{
+        walletAddress: string;
+        publicNonce: string;
+        signature: string;
+    }>;
+    /**
+     * Unshields (moves from private/confidential back to revealed) `revealedOutAmount` of this
+     * account's shielded balance for `resourceAddress` — see `ShieldedOutputRecord`'s doc comment
+     * for why a known local record is the only way to spend one (no client-side scan-by-view-key
+     * API exists for stealth UTXOs). Which specific output(s) to spend is decided internally by
+     * `resolveUnshieldPlan`'s coin selection (largest-first, spending more than one in the same
+     * transaction via repeated `spendStealthInput()` calls if a single output isn't enough) — the
+     * caller only supplies an amount, not a commitment.
+     *
+     * Two `StealthTransfer` builder requirements, confirmed directly against its `validate()`/
+     * `emitInstructions()` source (not assumed from the docs alone), shape this method:
+     *
+     * 1. `toRevealedOutput`/`payFeeFromRevealed` both require a revealed source account already
+     *    registered via `spendRevealedInput`, which itself requires an amount `> 0` — there is no
+     *    way to register just the account without withdrawing something. This method withdraws a
+     *    trivial `1n`-unit "dust" amount for that sole purpose and folds it straight back into the
+     *    revealed output (`revealedOutAmount + 1n`), so it costs nothing beyond the tx fee.
+     * 2. The builder always requires at least one stealth output — a "pure" 100%-revealed spend
+     *    with zero private remainder cannot be constructed in one step. This method always creates
+     *    a new stealth output for the selected inputs' total minus `revealedOutAmount` back to this
+     *    same account, so `resolveUnshieldPlan` guarantees that remainder is always `> 0`.
+     *
+     * Shares `shield()`'s mid-flight crash safety: the pending-shield ledger entry carries
+     * `spentCommitments` so `recoverPendingShields()` can both record the new change output *and*
+     * mark the spent ones, even if the service worker dies between finalization and the storage
+     * writes.
+     */
+    unshield(resourceAddress: string, revealedOutAmount: bigint, maxFee?: bigint, memo?: string): Promise<{
+        transactionId: string;
+    }>;
+    /**
+     * Withdraws `amount` of a Stealth-typed resource (e.g. XTR) from this account's revealed
+     * balance and feeds it, as a `Bucket` left on the workspace under `workspaceVarName`, into
+     * `followUpInstructions` — all in one signed transaction.
+     *
+     * This is the *only* way to move Stealth-typed funds into an arbitrary contract call. A plain
+     * `CallMethod withdraw` on a Stealth vault is not a standalone-valid instruction: confirmed
+     * empirically (isolated to a bare `withdraw` immediately followed by `deposit`, zero other
+     * instructions) that `account.execute()` fails it client-side, before ever reaching the
+     * network, with a generic `JSON deserialization failed: ... untagged enum TransactionInput`
+     * error. Moving Stealth funds anywhere always requires the native `StealthTransfer`
+     * instruction, signed via `WalletStealthAuthorizer` — which `execute()`/`TransactionBuilder`
+     * never invokes (see this file's own `execute()` doc comment, and the
+     * `isStealthTransferInstruction` guard + comment in `background/index.ts`). This method uses
+     * the *same* `StealthTransfer` builder + `WalletStealthAuthorizer` pipeline `shield()`/
+     * `unshield()` already use, extended with `toRevealedOutputAsBucket`/`andThen` (see
+     * `vendor/ootle-patched/README.md`) to leave the revealed output on the workspace instead of
+     * auto-depositing it back to this account, and to append the caller's own instructions after
+     * it in the same transaction.
+     *
+     * @param relatedComponents Every *other* component `followUpInstructions` touches (e.g. a
+     *   DAO contract being called). The `StealthTransfer` builder auto-registers this account's
+     *   own vaults as tx inputs, but has no way to know what the caller's own follow-up
+     *   instructions reference — the engine rejects a `CallMethod` touching an unregistered
+     *   substate with `SubstateNotFound`. Each is registered by address, plus every vault its own
+     *   state references (the same vault-discovery this account's own address already gets).
+     */
+    withdrawStealthAndExecute(resourceAddress: string, amount: bigint, workspaceVarName: string, followUpInstructions: Instruction[], relatedComponents?: string[], maxFee?: bigint): Promise<{
+        transactionId: string;
+    }>;
+    /**
+     * Funds an HTLC (hashed timelock contract): creates a stealth output for `amount` of
+     * `resourceAddress`, gated not by a normal one-time stealth key but by a two-leaf TIP-0006
+     * condition tree (`htlcConditions` in `./htlc.ts`) — a claim path admissible only to
+     * `claimantWalletAddress` (revealing the SHA-256 preimage of `hashLockHex`, before
+     * `refundEpoch`), and a refund path admissible only to this account (at/after `refundEpoch`).
+     * `htlcConditions`'s own doc comment covers the exact leaf shapes.
+     *
+     * This account never needs (and must never be given) the actual preimage — only its hash. The
+     * caller resolves `refundEpoch` from a desired wall-clock deadline via the provider/network's
+     * current epoch, the same as any other epoch-relative on-chain deadline.
+     *
+     * Returns the full `conditions` tree alongside the transaction id and this output's own
+     * commitment: only the tree's **root** is committed on-chain, so the claimant needs the exact
+     * leaves — out of band, via whatever swap protocol coordinates the two sides — to later reveal
+     * the claim leaf.
+     *
+     * Also returns `outputMask` (hex): this account funded the output, so it's the one place the
+     * blinding mask is ever available to it without decryption — `encrypted_data` is encrypted for
+     * `claimantWalletAddress`'s view key, not this account's, so if the claim path is never taken
+     * and this account later calls `htlcRefund`, it cannot decrypt the output the normal way (the
+     * way `htlcClaim`'s claimant can, since the output is addressed to *them*). Retaining this mask
+     * now — alongside the known `amount` — is what makes an undecryptable refund possible at all.
+     * `htlcRefund`'s own doc comment covers the rest.
+     *
+     * `destination` is set to the claimant's own wallet address (not this account's) so the
+     * claimant can independently decrypt and verify the funded amount themselves, the same as any
+     * other stealth payment addressed to them — spend authority is governed entirely separately, by
+     * `payTo`.
+     */
+    htlcFund(resourceAddress: string, amount: bigint, claimantWalletAddress: string, hashLockHex: string, refundEpoch: bigint, maxFee?: bigint): Promise<{
+        transactionId: string;
+        conditions: object[];
+        ownCommitment: string;
+        outputMask: string;
+    }>;
+    /**
+     * Claims a funded HTLC (the counterpart to `htlcFund`): reveals the claim leaf's SHA-256
+     * preimage to spend the script-path-locked output, moving `amount` into a brand-new, normal
+     * (freely key-spendable) stealth output owned by this account.
+     *
+     * This account must be the intended claimant — `htlcFund` addressed the output to this
+     * account's own wallet address, so it can unblind it the normal way: fetch the `utxo_...`
+     * substate and decrypt with this account's own view secret, exactly like `claimPrivatePayment`
+     * does for any other incoming stealth payment. `conditions` must be the *exact* two-leaf tree
+     * `htlcFund` returned (or was handed out of band) — the wrong tree produces a script-path
+     * witness whose condition root won't match the output's committed `SpendAuthorization::Script`
+     * root, and `buildStealthTransferStatement`/the network both reject the spend.
+     *
+     * Fees are paid from this account's own existing revealed balance via `pay_fee` (same as any
+     * other transaction this wallet submits), not from the claimed HTLC funds — a transaction's fee
+     * instructions execute in a separate phase *before* its main instructions, so the claim's own
+     * `StealthTransfer` instruction (a main instruction) can't fund its own fee even in principle.
+     *
+     * Bypasses `StealthTransfer`/`WalletStealthAuthorizer` entirely — that builder pipeline only
+     * ever produces key-path stealth inputs (a one-time DH signature per input), which doesn't
+     * apply here: this spend's authorization is the revealed script-path leaf itself (its
+     * `AccessRule` atom, satisfied by this account's normal transaction signature), not a stealth
+     * spend key. `buildStealthTransferStatement` (tari-project/tari-ootle#2431) produces the
+     * complete statement — inputs/outputs/balance proof/covenant claims — in one call from the
+     * unblinded mask+value and the two witnesses below, so there is nothing left for the builder
+     * pipeline to add.
+     */
+    htlcClaim(resourceAddress: string, commitmentHex: string, conditions: object[], preimageHex: string, maxFee?: bigint): Promise<{
+        transactionId: string;
+    }>;
+    /**
+     * Refunds an HTLC this account itself funded (via `htlcFund`), once `refundEpoch` has passed:
+     * reveals the refund leaf to spend the output back into a brand-new, normal (freely
+     * key-spendable) stealth output owned by this account.
+     *
+     * Unlike `htlcClaim`, this account **cannot** decrypt the output on-chain — `htlcFund` addressed
+     * it to the claimant's wallet, so `encrypted_data` is encrypted for the claimant's view key, not
+     * this account's. `amount` and `outputMaskHex` must be exactly what `htlcFund` returned (or
+     * otherwise already known — this account chose `amount` itself when funding, and `outputMaskHex`
+     * is `htlcFund`'s own return value for exactly this purpose): reconstructing the commitment from
+     * a wrong mask or amount fails cleanly (the resulting input just doesn't match the on-chain
+     * commitment, so the network rejects the spend) rather than silently, but there is no recovery
+     * path if this account discarded the mask — see `htlcFund`'s doc comment.
+     *
+     * Otherwise identical to `htlcClaim`: same fee-from-own-balance reasoning, same
+     * `buildStealthTransferStatement`-in-one-call approach, same bypass of
+     * `StealthTransfer`/`WalletStealthAuthorizer`.
+     */
+    htlcRefund(resourceAddress: string, commitmentHex: string, conditions: object[], amount: bigint, outputMaskHex: string, maxFee?: bigint): Promise<{
+        transactionId: string;
+    }>;
+    /**
+     * Sends `amount` of this account's shielded balance for `resourceAddress` directly to
+     * `recipientWalletAddress` — a private-to-private transfer, unlike `shield()` (which always
+     * targets this same account's own wallet address). The recipient never appears on-chain in the
+     * clear; only they (holding the matching view key) can discover the payment, and only by being
+     * told the resulting commitment out of band — same "no scan API" caveat as everywhere else
+     * stealth outputs are spent. Which specific output(s) to spend is decided internally by
+     * `resolveSendPrivatelyPlan`'s coin selection (largest-first, spending more than one in the same
+     * transaction via repeated `spendStealthInput()` calls if a single output isn't enough) — the
+     * caller only supplies an amount, not a commitment.
+     *
+     * Unlike `unshield()`, sending the *entire* selected total with no remainder is possible in one
+     * step here: the builder's "at least one stealth output" requirement is trivially satisfied by
+     * the recipient's own output, with no need for a same-account dust/change output to satisfy it.
+     * Change (if `amount` is less than the selected inputs' total) is a second stealth output back
+     * to this account.
+     *
+     * The fee-paying "dust" trick from `unshield()` still applies for the same reason: pay_fee and
+     * (when there's change) the *concept* of "this account received a new output" both need a
+     * revealed source account registered via `spendRevealedInput`, which requires amount `> 0`.
+     *
+     * Crash-safety: this account's own change commitment (if any) is read directly from the
+     * locally-built outputs statement, *not* inferred from the finalized transaction's
+     * `up_substates` — those also contain the recipient's brand-new stealth output, and naively
+     * grabbing "the first new stealth output" would risk recording the recipient's payment as our
+     * own. See `PendingShield.ownCommitment`'s doc comment.
+     */
+    sendPrivately(resourceAddress: string, recipientWalletAddress: string, amount: bigint, maxFee?: bigint, memo?: string, minimumValuePromise?: bigint): Promise<{
+        transactionId: string;
+        recipientCommitment: string;
+        recipientSubstateId: string;
+        minimumValuePromise: string;
+    }>;
+    /**
+     * The recipient-side counterpart to `sendPrivately()`'s commitment hand-off: given a commitment
+     * shared out of band, fetches the corresponding `utxo_{resource}_{commitment}` substate and
+     * tries to decrypt it with this account's own view secret. `decryptOwnedUtxo` swallows the
+     * "not ours" throw and returns `null` instead, so a wrong/foreign commitment fails cleanly here
+     * rather than looking like a network error. Success both *proves* ownership and recovers the
+     * amount in one step (no need to be told the amount separately) -- recorded exactly like a
+     * self-shield's output, so it then just shows up in this account's private balance and
+     * shielded-outputs picker.
+     */
+    claimPrivatePayment(resourceAddress: string, commitmentHex: string): Promise<{
+        amount: bigint;
+        memo?: string;
+    }>;
+    /**
+     * This account's unspent stealth outputs, newest first, optionally filtered to one resource.
+     *
+     * This local ledger *is* the account's private position -- see `ShieldedOutputRecord`'s doc
+     * comment for why it has to be: a stealth output is a freestanding
+     * `utxo_{resource}_{commitment}` substate, not an entry in any vault, and there is no
+     * scan-by-view-key API that could rediscover one from the chain alone given only its commitment.
+     * Anything not in here is, as far as this wallet is concerned, not spendable.
+     */
+    listUnspentShieldedOutputs(resourceAddress?: string): Promise<ShieldedOutputRecord[]>;
+    /**
+     * Per-resource totals over `listUnspentShieldedOutputs()`, with each resource's real on-chain
+     * `divisibility`/symbol/name folded in (the same lookup `getBalances()` does, via the shared
+     * `fetchResourceMetadata` helper -- a private balance has to be renderable on its own, without a
+     * caller cross-referencing `getBalances()` for the decimals).
+     *
+     * Distinct from `getBalances()`'s `confidentialAmount` in two ways worth being precise about:
+     * it counts only these freestanding stealth outputs (not a Confidential *vault*'s own
+     * commitments map, which `getBalances()` also decrypts and adds in), and it reports a resource
+     * whose only holding is private, which `getBalances()` only surfaces via its
+     * `synthesizeShieldedOnlyBalances` path. For "what can I spend privately right now", this is the
+     * authoritative number, because it is exactly what `resolveUnshieldPlan`/
+     * `resolveSendPrivatelyPlan` select from.
+     *
+     * One network round trip (the resource metadata batch); the amounts themselves are local.
+     */
+    getPrivateBalances(): Promise<PrivateBalance[]>;
+    /**
+     * Automatic counterpart to `claimPrivatePayment()`: instead of requiring the recipient be told a
+     * commitment out of band, walks the indexer's recent-transaction history looking for
+     * `StealthTransfer` outputs this account can decrypt with its own view key (see
+     * `scanTransactionsForOwnedOutputs`'s doc comment for why the data needed to do this is present
+     * even in the *pruned* form `listRecentTransactions` returns).
+     *
+     * Cursor-based (`privatePaymentScanCursors[accountId]`, the newest transaction id seen last time)
+     * so this can run cheaply and opportunistically on every `popup-get-status` — see
+     * `buildStatus()`'s `recoverPendingShields()` call for the same pattern. Walks backward in pages
+     * of `pageSize` (oldest-paging via `last_id`, per the indexer's own "recent" convention) up to
+     * `maxPages`, stopping early once it reaches the transaction id it left off at last time. A very
+     * active chain producing more than `maxPages * pageSize` new transactions between scans will
+     * only be caught up partway; the next scan resumes from the same cursor and continues.
+     */
+    scanForPrivatePayments(maxPages?: number, pageSize?: number): Promise<{
+        claimed: number;
+        found: ScannedStealthOutput[];
+    }>;
+}
+/**
+ * Reads the commitment of the output at `outputIndex` (in the order `toStealthOutput()` was
+ * called) directly from the outputs statement `StealthTransfer.prepare()` already built —
+ * generated client-side, so it's known *before* submission, not inferred afterward by scanning
+ * the finalized transaction's `up_substates`. That scan-based approach is unambiguous when a
+ * transfer only ever creates one new stealth output belonging to this account (shield, unshield),
+ * but breaks down the moment a transfer also creates a *different* account's new stealth output
+ * in the same transaction (a private send's recipient output) — grabbing "the first new stealth
+ * output" from `up_substates` would then risk attributing someone else's payment to us.
+ */
+/**
+ * Builds a complete `StealthTransferStatement` (as its final compact JSON string) that spends one
+ * script-path-locked HTLC UTXO into one brand-new, normal (key-spendable) stealth output — the
+ * shared core of `htlcClaim`/`htlcRefund`, which differ only in which leaf they reveal and how
+ * they come by the input's `mask`/`value` (on-chain decryption for a claim; retained from funding
+ * time for a refund, since the funder can't decrypt an output addressed to the claimant).
+ *
+ * Every JSON fragment here is spliced from the raw strings `buildScriptPathWitness`/
+ * `createStealthOutputWitness` themselves return, never `JSON.parse`d and rebuilt — both carry
+ * u64 fields (amounts, epochs) that can exceed `Number.MAX_SAFE_INTEGER`, and a parse/restringify
+ * round-trip through a JS number would silently corrupt them. `value` is spliced in from `params`
+ * via template-literal interpolation of a `bigint`, which stringifies to its exact decimal digits
+ * with no such risk.
+ */
+export declare function buildHtlcSpendStatement(params: {
+    network: Network;
+    conditions: object[];
+    leaf: object;
+    /** The revealed leaf's witness data -- the preimage for a claim, empty for a refund (the
+     * refund leaf has no data-consuming `HashLock` atom). */
+    data: Uint8Array;
+    mask: string;
+    value: bigint;
+    destinationWalletAddress: string;
+    resourceAddress: string;
+}): string;
+/**
+ * Synthesizes a `TokenBalance` entry for each resource whose only balance is a shielded output
+ * with no on-chain vault at all (e.g. redeemed via the "Advanced" unshield flow from someone
+ * else's shared commitment) -- these never appear in `getBalances()`'s vault-derived `parsed`
+ * list, since they're freestanding `utxo_{resource}_{commitment}` substates, not vault entries.
+ * Skips any resource already covered by `parsedResources` (that one gets its shielded amount
+ * folded into its existing entry instead, in `getBalances()` itself).
+ */
+export declare function synthesizeShieldedOnlyBalances(parsedResources: Set<string>, shieldedByResource: Map<string, bigint>, divisibilityByResource: Map<string, number>, symbolByResource: Map<string, string | null>, nameByResource: Map<string, string | null>): TokenBalance[];
+/**
+ * Coin selection for spending shielded outputs: picks this resource's unspent records
+ * largest-first until their sum covers `targetAmount`, so a spend needing more than any single
+ * output holds is satisfied by combining several in one transaction (the builder's
+ * `spendStealthInput()` can be called once per input UTXO) rather than requiring the caller to
+ * pick one record themselves. Largest-first minimizes the number of inputs spent (each one adds
+ * real signature/proof-verification fee cost), rather than needlessly consolidating dust.
+ *
+ * Returns the unselected remainder too (still sorted largest-first) so callers that need "at
+ * least one more unit available" (see `resolveUnshieldPlan`) can pull in exactly one more output
+ * without re-deriving the candidate list.
+ */
+/**
+ * The unspent subset of a shielded-output ledger, newest first, optionally narrowed to one
+ * resource. Newest-first is a display order, deliberately *not* the spend order: coin selection is
+ * `selectShieldedUtxosForAmount`'s largest-first job, and the two must not be conflated.
+ *
+ * Split out of `OotleAccount.listUnspentShieldedOutputs` (which is just this over the account's own
+ * stored records) so the filtering rule -- what counts as spendable, and what a dApp with view
+ * access is allowed to see -- is testable on its own.
+ */
+export declare function selectUnspentShieldedOutputs(records: ShieldedOutputRecord[], resourceAddress?: string): ShieldedOutputRecord[];
+/**
+ * Totals a set of already-unspent shielded outputs per resource. `outputCount` is carried
+ * alongside the sum rather than left to be recomputed, because it is not cosmetic: each output is
+ * spent whole, so the count is what bounds whether a given amount can actually be covered (see
+ * `resolveUnshieldPlan`) -- a balance of 100 across one output and across fifty are very different
+ * things to a caller planning a spend.
+ *
+ * Insertion-ordered by first appearance (Map iteration order), so a caller's rendering doesn't
+ * reshuffle between calls for no reason.
+ */
+export declare function summarizePrivateHoldings(records: ShieldedOutputRecord[]): {
+    resourceAddress: string;
+    amount: bigint;
+    outputCount: number;
+}[];
+export declare function selectShieldedUtxosForAmount(records: ShieldedOutputRecord[], resourceAddress: string, targetAmount: bigint): {
+    selected: ShieldedOutputRecord[];
+    total: bigint;
+    unselected: ShieldedOutputRecord[];
+};
+/**
+ * Pure planning for `unshield()`: selects enough of the caller's unspent records for this
+ * resource (via `selectShieldedUtxosForAmount`) to cover `revealedOutAmount`, and checks the
+ * total leaves at least 1 unit as private remainder (see `unshield()`'s doc comment for why the
+ * upper bound is strict, not `<=`). Extracted so this decision logic is unit-testable without a
+ * live provider/WASM crypto, same reasoning as `pollTransactionResult`'s extraction.
+ *
+ * If the minimal selection's total lands *exactly* on `revealedOutAmount` (zero remainder), and
+ * another unspent record for this resource exists, one more (the smallest available) is pulled
+ * in purely to create a nonzero remainder — spending an extra UTXO is preferable to failing a
+ * reveal that the account's total private balance could otherwise satisfy.
+ */
+export declare function resolveUnshieldPlan(records: ShieldedOutputRecord[], resourceAddress: string, revealedOutAmount: bigint): {
+    commitments: string[];
+    remainder: bigint;
+};
+/**
+ * Pure planning for `sendPrivately()`: selects enough of the caller's unspent records for this
+ * resource to cover `amount` — unlike `resolveUnshieldPlan`, sending the *entire* selected total
+ * with zero change is allowed, since the recipient's own stealth output already satisfies the
+ * builder's "at least one stealth output" requirement (no same-account dust output is needed to
+ * satisfy it, unlike unshield's revealed destination). Extracted for the same unit-testability
+ * reasons as `resolveUnshieldPlan`.
+ */
+export declare function resolveSendPrivatelyPlan(records: ShieldedOutputRecord[], resourceAddress: string, amount: bigint): {
+    commitments: string[];
+    changeAmount: bigint;
+};
+/**
+ * Reconciles shields whose `pollTransactionResult` never got to finish (the extension's service
+ * worker was killed between submission and the storage write) — see `PendingShield`'s doc
+ * comment. Checks each pending shield's current status *once* (not a blocking poll-to-finalize
+ * loop — if it's still genuinely pending, this leaves it for the next check rather than stalling
+ * whatever triggered recovery, typically `popup-get-status`) and either completes the storage
+ * write (finalized successfully), drops it (rejected — no stealth output was ever created, so
+ * there's nothing to recover), or leaves it alone (still pending). One provider is reused across
+ * every pending shield, whichever local account they belong to — this is a read-only connection,
+ * not account/signing-specific.
+ */
+export declare function recoverPendingShields(provider: IndexerProvider): Promise<void>;
+/**
+ * Forgets what we thought we knew about these substates' versions, after the chain has told us a
+ * remembered one is unusable. Keeping it would make `applyKnownVersions` reassert it over every
+ * future resolve, turning one bad write into a permanently stuck wallet.
+ */
+export declare function forgetKnownVersions(substateIds: string[]): Promise<void>;
+/** Drops the in-memory known-versions cache. Call this on wallet reset so a freshly-created wallet
+ * can't inherit the previous wallet's cached version numbers — the persisted side of that wipe is
+ * the caller's own responsibility (a serialized clear of whatever `KeyValueStore` backs `storage.ts`). */
+export declare function resetKnownVersions(): void;
+/**
+ * Polls a submitted transaction's result to finalization (or rejection/timeout). Extracted from
+ * `OotleAccount.submitReal()` so `shield()`/`unshield()` — which submit via a completely
+ * different pipeline (`StealthTransfer`/`WalletStealthAuthorizer`/`submitTransaction`, not
+ * `TransactionBuilder`) — share the exact same hardened Reject/AcceptFeeRejectRest/timeout
+ * handling instead of a second, potentially-drifting copy of it.
+ */
+export declare function pollTransactionResult(provider: IndexerProvider, transactionId: string, timeoutMs?: number): Promise<IndexerGetTransactionResultResponse>;
+export declare function resolveInputsWithRetry(provider: IndexerProvider, requirements: SubstateRequirement[], retries?: number, retryDelayMs?: number): Promise<SubstateRequirement[]>;
+/**
+ * Checks whether `substateId` already exists on-chain, tolerating a couple of retries in case it
+ * just hasn't finalized on the indexer yet (a much smaller budget than `resolveInputsWithRetry`'s
+ * default — this is used to *decide* whether to create something, not to wait out a known producer,
+ * so a persistent 404 should read as "doesn't exist" quickly rather than stall the caller). Only
+ * `resolveInputsWithRetry`'s specific "not yet finalized" 404 is treated as "missing" — any other
+ * failure (network error, indexer down) propagates rather than being silently read as nonexistence,
+ * since that misread would make `send()` prepend a `CreateAccount` for an account that actually
+ * exists, which the engine rejects outright ("is already UP and conflicts with an existing output").
+ */
+export declare function substateExists(provider: IndexerProvider, substateId: string): Promise<boolean>;
+export declare function extractMissingSubstateAddress(message: string): string | null;
+export declare function extractStaleLockVersion(message: string): {
+    substateId: string;
+    version: number;
+} | null;
+//# sourceMappingURL=wallet.d.ts.map