@upshiftfinance/sdk 0.0.0-stage → 0.1.0

package/lib/adapters/solana/withdrawal-queue.d.ts

@@ -0,0 +1,125 @@
+import { type Connection, PublicKey } from '@solana/web3.js';
+import type { IAddress, ISolanaNetwork, IVaultAvailableRedemption } from '../../types';
+import { VaultRedemptionStatus } from '../../types/vaults';
+import type { IVaultWithdrawalQueue } from '../../types/vaults';
+import type { ISolanaVaultState, ISolanaWithdrawalRequestState } from './types';
+/**
+ * The queue PDA for a vault: `["withdrawal_queue", vault_state]` under the queue
+ * program. The vault only ever attaches this address.
+ *
+ * @param vaultState - The vault's `VaultState` account.
+ * @param queueProgramId - The august_withdrawal_queue program id for the network.
+ */
+export declare function deriveWithdrawalQueuePda(vaultState: PublicKey, queueProgramId: PublicKey): PublicKey;
+/**
+ * Where a request stands at `nowSeconds`, by the program's own rules
+ * (`WithdrawalRequest::is_expired` / `is_eligible`): a non-zero `expiresAt` at
+ * or before now is expired, and that is checked first because an expired
+ * request can only be cancelled; otherwise it is claimable from `eligibleAt`.
+ *
+ * @param request - Decoded request; `eligibleAt` / `expiresAt` in Unix seconds.
+ * @param nowSeconds - Unix seconds. Wall-clock time stands in for the chain's
+ *   clock, so a request within seconds of a boundary may be classified a slot
+ *   early or late.
+ */
+export declare function classifyWithdrawalRequest(request: Pick<ISolanaWithdrawalRequestState, 'eligibleAt' | 'expiresAt'>, nowSeconds: number): VaultRedemptionStatus;
+/**
+ * What finalizing `shares` would pay the recipient at the vault's current
+ * state: the offset-aware `assets_for_redeem`, less the ceil-rounded
+ * withdrawal fee. Finalize prices at execution, so this is an estimate.
+ *
+ * @returns Raw deposit-mint units, net of fee.
+ * @throws UpshiftValidationError when the vault has no share price.
+ */
+export declare function estimateRequestPayout(input: {
+    vaultState: Pick<ISolanaVaultState, 'localAum' | 'deployedAum' | 'withdrawalFee' | 'shareOffset'>;
+    supply: bigint;
+    shares: bigint;
+}): bigint;
+/**
+ * The withdrawal queue program id a Solana service names, or `undefined` when
+ * it names none: the queue is not deployed on its network, or the service has
+ * neither `network` nor `getProgramId`. Read
+ * paths treat that as "no queue" rather than a failed read, so they make no RPC
+ * call and log nothing.
+ *
+ * Prefers `network`, read straight from `programIds`: `getProgramId` is an
+ * instrumented public method, and calling it where it throws by design would
+ * record an error breadcrumb on every vault read.
+ *
+ * @param service - The SolanaAdapter (or a stand-in) the read was given.
+ * @returns The queue program id, or `undefined`.
+ * @throws When the service names a malformed id; callers read inside their
+ *   own `try`, so that is logged as a failed queue read.
+ */
+export declare function resolveQueueProgramId(service: {
+    network?: ISolanaNetwork;
+    getProgramId?: (type: 'vault' | 'withdrawalQueue') => string;
+}): PublicKey | undefined;
+/**
+ * The vault's withdrawal queue summary for `IVault.withdrawalQueue`, or
+ * `undefined` when the vault has no queue.
+ *
+ * `enabled` is whether the vault's redeem gate points at this queue, read from
+ * the vault state in the same call as the queue, so an attach or release shows
+ * at once rather than when a cached vault state expires. A queue that was
+ * released keeps its account and may still hold pending requests, so it is
+ * reported with `enabled: false`.
+ *
+ * RPC: one `getMultipleAccountsInfo` (the queue and the vault state). Not
+ * cached: the counters change with every request.
+ *
+ * @param input - The vault and where to read.
+ */
+export declare function getSolanaWithdrawalQueueSummary(input: {
+    connection: Connection;
+    queueProgramId: PublicKey;
+    /** The vault's `VaultState` account. */
+    vaultState: PublicKey;
+    /** Decimals of the vault's share mint, for `pendingShares`. */
+    shareDecimals: number;
+}): Promise<IVaultWithdrawalQueue | undefined>;
+/**
+ * `owner`'s pending requests on a vault's queue, split the way the EVM path
+ * splits them: `availableRedemptions` holds requests still waiting
+ * (`AWAITING_COOLDOWN`) or past their window (`EXPIRED`, cancel-only);
+ * `pendingRedemptions` holds requests finalizable now (`READY_TO_CLAIM`).
+ *
+ * Each entry's `amount` is the escrowed shares and `estimatedAssets` the net
+ * payout at the current share price (see {@link estimateRequestPayout}),
+ * priced from the vault state and share supply of a single slot, never from a
+ * cached state. `receiver` is the wallet that owns the request's payout token
+ * account, which need not be the requester; if that account is gone it is the
+ * account address itself. `id` and `hash` are the request account's address:
+ * the program keeps no creation transaction to point at. `date` and
+ * `day` / `month` / `year` are the eligibility time (UTC); `timestamp` is when
+ * the request was made.
+ *
+ * RPC, worst case: one `getAccountInfo` (skipped once the queue is known to
+ * exist), one `getProgramAccounts` filtered on queue and owner, and, when the
+ * owner has any request, one `getMultipleAccountsInfo` carrying the vault
+ * state, share mint and up to 98 distinct payout accounts. Each further 100
+ * distinct payout accounts cost one more `getMultipleAccountsInfo`, at most
+ * four in flight. A vault without a queue costs the single `getAccountInfo`.
+ *
+ * @param input - The vault, the owner, and where to read.
+ */
+export declare function getSolanaWithdrawalRedemptions(input: {
+    connection: Connection;
+    queueProgramId: PublicKey;
+    /** The vault's `VaultState` account, read fresh for pricing. */
+    vaultStateAddress: PublicKey;
+    /** The vault's share mint, read in the same call for the supply. */
+    shareMint: PublicKey;
+    /** The holder whose requests to list. */
+    owner: PublicKey;
+    /** The vault address to stamp on each entry. */
+    vault: IAddress;
+    /** Deposit mint decimals, for `estimatedAssets`. */
+    depositDecimals: number;
+    /** Unix seconds to classify against; defaults to now. */
+    nowSeconds?: number;
+}): Promise<{
+    availableRedemptions: IVaultAvailableRedemption[];
+    pendingRedemptions: IVaultAvailableRedemption[];
+}>;

package/lib/adapters/solana/withdrawal-queue.js

@@ -0,0 +1,301 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveWithdrawalQueuePda = deriveWithdrawalQueuePda;
+exports.classifyWithdrawalRequest = classifyWithdrawalRequest;
+exports.estimateRequestPayout = estimateRequestPayout;
+exports.resolveQueueProgramId = resolveQueueProgramId;
+exports.getSolanaWithdrawalQueueSummary = getSolanaWithdrawalQueueSummary;
+exports.getSolanaWithdrawalRedemptions = getSolanaWithdrawalRedemptions;
+/**
+ * Read paths for the august_withdrawal_queue program: the per-vault queue
+ * summary and a holder's pending withdrawal requests.
+ *
+ * Internal to the SDK. `getSolanaVault` uses {@link getSolanaWithdrawalQueueSummary};
+ * `getVaultPositions` and `getVaultAvailableRedemptions` use
+ * {@link getSolanaWithdrawalRedemptions}. Nothing here signs or writes.
+ */
+const anchor_1 = require("@coral-xyz/anchor");
+const spl_token_1 = require("@solana/spl-token");
+const web3_js_1 = require("@solana/web3.js");
+const core_1 = require("../../core");
+const cache_1 = require("../../core/cache");
+const concurrency_1 = require("../../core/helpers/concurrency");
+const vaults_1 = require("../../types/vaults");
+const vault_idl_1 = require("./idl/vault-idl");
+const withdrawal_queue_idl_1 = require("./idl/withdrawal-queue-idl");
+const pricing_1 = require("./pricing");
+const constants_1 = require("./constants");
+const utils_1 = require("./utils");
+const token_reads_1 = require("./token-reads");
+const WITHDRAWAL_QUEUE_SEED = 'withdrawal_queue';
+/** Byte offsets of `queue` and `owner` in a `WithdrawalRequest`, after the 8-byte discriminator. */
+const REQUEST_QUEUE_OFFSET = 8;
+const REQUEST_OWNER_OFFSET = 40;
+/** `getMultipleAccountsInfo` accepts at most this many accounts per call. */
+const MAX_ACCOUNTS_PER_CALL = 100;
+/** Payout-account batches beyond the first, in flight at once. */
+const PAYOUT_BATCH_CONCURRENCY = 4;
+/**
+ * The queue PDA for a vault: `["withdrawal_queue", vault_state]` under the queue
+ * program. The vault only ever attaches this address.
+ *
+ * @param vaultState - The vault's `VaultState` account.
+ * @param queueProgramId - The august_withdrawal_queue program id for the network.
+ */
+function deriveWithdrawalQueuePda(vaultState, queueProgramId) {
+    return web3_js_1.PublicKey.findProgramAddressSync([Buffer.from(WITHDRAWAL_QUEUE_SEED), vaultState.toBuffer()], queueProgramId)[0];
+}
+/** A read-only queue program client on `connection`. No wallet, no RPC on construction. */
+function queueProgram(connection, queueProgramId) {
+    return new anchor_1.Program({ ...withdrawal_queue_idl_1.withdrawalQueueIdl, address: queueProgramId.toBase58() }, utils_1.SolanaUtils.getReadOnlyProvider({ connection }));
+}
+/** A read-only vault program client, used only for its account coder. */
+function vaultProgram(connection) {
+    return new anchor_1.Program(vault_idl_1.vaultIdl, utils_1.SolanaUtils.getReadOnlyProvider({ connection }));
+}
+/**
+ * Where a request stands at `nowSeconds`, by the program's own rules
+ * (`WithdrawalRequest::is_expired` / `is_eligible`): a non-zero `expiresAt` at
+ * or before now is expired, and that is checked first because an expired
+ * request can only be cancelled; otherwise it is claimable from `eligibleAt`.
+ *
+ * @param request - Decoded request; `eligibleAt` / `expiresAt` in Unix seconds.
+ * @param nowSeconds - Unix seconds. Wall-clock time stands in for the chain's
+ *   clock, so a request within seconds of a boundary may be classified a slot
+ *   early or late.
+ */
+function classifyWithdrawalRequest(request, nowSeconds) {
+    const expiresAt = BigInt(request.expiresAt.toString());
+    const now = BigInt(nowSeconds);
+    if (expiresAt !== 0n && now >= expiresAt) {
+        return vaults_1.VaultRedemptionStatus.EXPIRED;
+    }
+    if (now >= BigInt(request.eligibleAt.toString())) {
+        return vaults_1.VaultRedemptionStatus.READY_TO_CLAIM;
+    }
+    return vaults_1.VaultRedemptionStatus.AWAITING_COOLDOWN;
+}
+/**
+ * What finalizing `shares` would pay the recipient at the vault's current
+ * state: the offset-aware `assets_for_redeem`, less the ceil-rounded
+ * withdrawal fee. Finalize prices at execution, so this is an estimate.
+ *
+ * @returns Raw deposit-mint units, net of fee.
+ * @throws UpshiftValidationError when the vault has no share price.
+ */
+function estimateRequestPayout(input) {
+    const { vaultState, supply, shares } = input;
+    const gross = (0, pricing_1.assetsForRedeem)({
+        supply,
+        totalAssets: (0, pricing_1.totalAssetsOf)(vaultState),
+        shares,
+        offset: (0, pricing_1.resolveShareOffset)(vaultState.shareOffset),
+    });
+    return (gross -
+        (0, pricing_1.withdrawalFee)(gross, (0, pricing_1.toBigInt)(vaultState.withdrawalFee, 'withdrawalFee')));
+}
+/**
+ * Whether the vault's queue account exists, remembering a yes. A queue is never
+ * closed once created (release keeps it so the vault can re-attach), so a
+ * positive answer is safe to cache; a negative one is not, and costs one
+ * `getAccountInfo` each time.
+ */
+async function queueExists(connection, queue) {
+    const cacheKey = `withdrawalQueueExists-${queue.toBase58()}`;
+    if (await (0, cache_1.getSafeCache)(cacheKey))
+        return true;
+    const exists = (await connection.getAccountInfo(queue)) !== null;
+    if (exists)
+        await (0, cache_1.setSafeCache)(cacheKey, true);
+    return exists;
+}
+/**
+ * The wallet a request pays: the owner (authority) of its payout token account.
+ * A request may pay someone other than its requester, so this is read from the
+ * account rather than assumed. If the account is gone or is not a token
+ * account, its address is the best identification there is, and is returned
+ * as is; finalizing such a request would fail until the account is restored.
+ */
+function payoutWallet(tokenAccount, info) {
+    if (!info)
+        return tokenAccount.toBase58();
+    try {
+        return (0, spl_token_1.unpackAccount)(tokenAccount, info, info.owner).owner.toBase58();
+    }
+    catch {
+        return tokenAccount.toBase58();
+    }
+}
+/**
+ * The withdrawal queue program id a Solana service names, or `undefined` when
+ * it names none: the queue is not deployed on its network, or the service has
+ * neither `network` nor `getProgramId`. Read
+ * paths treat that as "no queue" rather than a failed read, so they make no RPC
+ * call and log nothing.
+ *
+ * Prefers `network`, read straight from `programIds`: `getProgramId` is an
+ * instrumented public method, and calling it where it throws by design would
+ * record an error breadcrumb on every vault read.
+ *
+ * @param service - The SolanaAdapter (or a stand-in) the read was given.
+ * @returns The queue program id, or `undefined`.
+ * @throws When the service names a malformed id; callers read inside their
+ *   own `try`, so that is logged as a failed queue read.
+ */
+function resolveQueueProgramId(service) {
+    if (service.network) {
+        const id = (0, constants_1.getDeployedProgramIds)(service.network)?.withdrawalQueue;
+        return id ? new web3_js_1.PublicKey(id) : undefined;
+    }
+    if (!service.getProgramId)
+        return undefined;
+    try {
+        return new web3_js_1.PublicKey(service.getProgramId('withdrawalQueue'));
+    }
+    catch (error) {
+        if (error instanceof core_1.UpshiftValidationError)
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * The vault's withdrawal queue summary for `IVault.withdrawalQueue`, or
+ * `undefined` when the vault has no queue.
+ *
+ * `enabled` is whether the vault's redeem gate points at this queue, read from
+ * the vault state in the same call as the queue, so an attach or release shows
+ * at once rather than when a cached vault state expires. A queue that was
+ * released keeps its account and may still hold pending requests, so it is
+ * reported with `enabled: false`.
+ *
+ * RPC: one `getMultipleAccountsInfo` (the queue and the vault state). Not
+ * cached: the counters change with every request.
+ *
+ * @param input - The vault and where to read.
+ */
+async function getSolanaWithdrawalQueueSummary(input) {
+    const queue = deriveWithdrawalQueuePda(input.vaultState, input.queueProgramId);
+    const [queueInfo, vaultStateInfo] = await input.connection.getMultipleAccountsInfo([queue, input.vaultState]);
+    if (!queueInfo || !vaultStateInfo)
+        return undefined;
+    // Decoded by name, so an account of another type at either address throws
+    // rather than being read as this one.
+    const state = queueProgram(input.connection, input.queueProgramId).coder.accounts.decode('withdrawalQueue', queueInfo.data);
+    const gate = vaultProgram(input.connection).coder.accounts.decode('vaultState', vaultStateInfo.data).withdrawalQueueAuthority;
+    return {
+        address: queue.toBase58(),
+        enabled: gate ? new web3_js_1.PublicKey(gate).equals(queue) : false,
+        cooldownSeconds: state.cooldownSeconds.toNumber(),
+        fulfillmentWindowSeconds: state.fulfillmentWindowSeconds.toNumber(),
+        pendingCount: state.pendingRequests.toNumber(),
+        pendingShares: (0, core_1.toNormalizedBn)(BigInt(state.pendingShares.toString()), input.shareDecimals),
+    };
+}
+/**
+ * `owner`'s pending requests on a vault's queue, split the way the EVM path
+ * splits them: `availableRedemptions` holds requests still waiting
+ * (`AWAITING_COOLDOWN`) or past their window (`EXPIRED`, cancel-only);
+ * `pendingRedemptions` holds requests finalizable now (`READY_TO_CLAIM`).
+ *
+ * Each entry's `amount` is the escrowed shares and `estimatedAssets` the net
+ * payout at the current share price (see {@link estimateRequestPayout}),
+ * priced from the vault state and share supply of a single slot, never from a
+ * cached state. `receiver` is the wallet that owns the request's payout token
+ * account, which need not be the requester; if that account is gone it is the
+ * account address itself. `id` and `hash` are the request account's address:
+ * the program keeps no creation transaction to point at. `date` and
+ * `day` / `month` / `year` are the eligibility time (UTC); `timestamp` is when
+ * the request was made.
+ *
+ * RPC, worst case: one `getAccountInfo` (skipped once the queue is known to
+ * exist), one `getProgramAccounts` filtered on queue and owner, and, when the
+ * owner has any request, one `getMultipleAccountsInfo` carrying the vault
+ * state, share mint and up to 98 distinct payout accounts. Each further 100
+ * distinct payout accounts cost one more `getMultipleAccountsInfo`, at most
+ * four in flight. A vault without a queue costs the single `getAccountInfo`.
+ *
+ * @param input - The vault, the owner, and where to read.
+ */
+async function getSolanaWithdrawalRedemptions(input) {
+    const availableRedemptions = [];
+    const pendingRedemptions = [];
+    const queue = deriveWithdrawalQueuePda(input.vaultStateAddress, input.queueProgramId);
+    if (!(await queueExists(input.connection, queue))) {
+        return { availableRedemptions, pendingRedemptions };
+    }
+    const requests = await queueProgram(input.connection, input.queueProgramId).account.withdrawalRequest.all([
+        { memcmp: { offset: REQUEST_QUEUE_OFFSET, bytes: queue.toBase58() } },
+        { memcmp: { offset: REQUEST_OWNER_OFFSET, bytes: input.owner.toBase58() } },
+    ]);
+    if (requests.length === 0) {
+        return { availableRedemptions, pendingRedemptions };
+    }
+    // Payout accounts, deduplicated: requests often share one. The first batch
+    // rides with the vault state and share mint, which must share a slot to
+    // price coherently; the rest only name receivers, so they need not.
+    const payoutAccounts = [
+        ...new Map(requests.map(({ account }) => [
+            account.recipientTokenAccount.toBase58(),
+            account.recipientTokenAccount,
+        ])).values(),
+    ];
+    const firstBatch = payoutAccounts.slice(0, MAX_ACCOUNTS_PER_CALL - 2);
+    const laterBatches = [];
+    for (let i = firstBatch.length; i < payoutAccounts.length; i += MAX_ACCOUNTS_PER_CALL) {
+        laterBatches.push(payoutAccounts.slice(i, i + MAX_ACCOUNTS_PER_CALL));
+    }
+    const [snapshot, laterInfos] = await Promise.all([
+        (0, token_reads_1.readPricingSnapshot)({
+            connection: input.connection,
+            program: vaultProgram(input.connection),
+            vaultStatePda: input.vaultStateAddress,
+            shareMintAddr: input.shareMint,
+            extraAccounts: firstBatch,
+        }),
+        (0, concurrency_1.mapWithConcurrency)(laterBatches, PAYOUT_BATCH_CONCURRENCY, (batch) => input.connection.getMultipleAccountsInfo(batch)),
+    ]);
+    const { vaultStateData, supply, shareDecimals } = snapshot;
+    const payoutInfos = [...snapshot.extraAccountInfos, ...laterInfos.flat()];
+    const payoutInfoOf = new Map(payoutAccounts.map((address, i) => [address.toBase58(), payoutInfos[i]]));
+    const now = input.nowSeconds ?? Math.floor(Date.now() / 1000);
+    for (const { publicKey, account } of requests) {
+        const shares = BigInt(account.shares.toString());
+        const eligibleAt = account.eligibleAt.toNumber();
+        const date = new Date(eligibleAt * 1000);
+        const status = classifyWithdrawalRequest(account, now);
+        let estimatedAssets;
+        try {
+            estimatedAssets = (0, core_1.toNormalizedBn)(estimateRequestPayout({ vaultState: vaultStateData, supply, shares }), input.depositDecimals);
+        }
+        catch (error) {
+            // A vault with no share price (assets zero against outstanding shares)
+            // has nothing to quote; the request itself is still listed.
+            core_1.Logger.log.warn('getSolanaWithdrawalRedemptions', 'No payout estimate', {
+                request: publicKey.toBase58(),
+                error,
+            });
+        }
+        const entry = {
+            id: publicKey.toBase58(),
+            hash: publicKey.toBase58(),
+            timestamp: account.requestedAt.toNumber(),
+            receiver: payoutWallet(account.recipientTokenAccount, payoutInfoOf.get(account.recipientTokenAccount.toBase58()) ?? null),
+            day: (0, core_1.toNormalizedBn)(date.getUTCDate(), 0),
+            month: (0, core_1.toNormalizedBn)(date.getUTCMonth() + 1, 0),
+            year: (0, core_1.toNormalizedBn)(date.getUTCFullYear(), 0),
+            amount: (0, core_1.toNormalizedBn)(shares, shareDecimals),
+            date,
+            vault: input.vault,
+            status,
+            ...(estimatedAssets && { estimatedAssets }),
+        };
+        if (status === vaults_1.VaultRedemptionStatus.READY_TO_CLAIM) {
+            pendingRedemptions.push(entry);
+        }
+        else {
+            availableRedemptions.push(entry);
+        }
+    }
+    return { availableRedemptions, pendingRedemptions };
+}
+//# sourceMappingURL=withdrawal-queue.js.map

package/lib/adapters/stellar/actions.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Stellar Vault Actions
+ *
+ * Builds unsigned Soroban transactions for vault deposit/redeem operations.
+ * Returns assembled XDR (base64) for wallet signing (e.g. Freighter).
+ */
+import type { IStellarDepositParams, IStellarRedeemParams } from './types';
+/**
+ * Deposit assets into a Stellar vault (self-deposit).
+ *
+ * Builds an unsigned Soroban transaction invoking the vault's `deposit` function.
+ * All three address roles (receiver, from, operator) are set to senderAddress.
+ *
+ * Contract signature: deposit(assets: i128, receiver: Address, from: Address, operator: Address) -> i128
+ *
+ * @returns Base64-encoded XDR of the unsigned transaction, ready for wallet signing.
+ */
+export declare function handleStellarDeposit(params: IStellarDepositParams): Promise<string>;
+/**
+ * Build an unsigned self-redeem Soroban transaction (receiver, owner, and
+ * operator all = `receiverAddress`). Assumes the deployed vault exposes
+ * `redeem(shares: i128, receiver, owner, operator) -> i128`; divergence
+ * surfaces as a generic Soroban simulation error.
+ *
+ * Side effect on failure: when the *vault* cannot serve the redemption — it
+ * rejected the call, or its ledger state needs restoring — the failure is
+ * reported to that vault's curator. Stellar vaults are instant-redeem only, so
+ * this is the curator's only signal that their depositors cannot get out.
+ * Fire-and-forget and deduped; see
+ * {@link reportRedeemFailure} and {@link REPORTED_BUILD_STAGES}.
+ *
+ * Note this includes a caller-caused rejection such as redeeming more shares
+ * than the wallet holds: the contract trapping is what we can observe, and
+ * telling that apart from a vault-side problem needs the vault's error
+ * taxonomy. A bad address, an unfunded account, and an exhausted RPC failover
+ * are excluded — none of those reached the vault.
+ *
+ * @returns Base64-encoded XDR ready for wallet signing; pass the signed
+ *   XDR to {@link submitStellarTransaction}.
+ */
+export declare function handleStellarRedeem(params: IStellarRedeemParams): Promise<string>;

package/lib/adapters/stellar/actions.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * Stellar Vault Actions
+ *
+ * Builds unsigned Soroban transactions for vault deposit/redeem operations.
+ * Returns assembled XDR (base64) for wallet signing (e.g. Freighter).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleStellarDeposit = handleStellarDeposit;
+exports.handleStellarRedeem = handleStellarRedeem;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const soroban_1 = require("./soroban");
+const utils_1 = require("./utils");
+const core_1 = require("../../core");
+const curator_alert_1 = require("../../core/logger/curator-alert");
+/**
+ * Build failures that mean the *vault* cannot serve a redemption right now, as
+ * opposed to a caller problem or a transport problem.
+ *
+ * `simulation` is the contract rejecting the call. `restore-required` is its
+ * ledger state having been archived, which blocks every redemption on the vault
+ * until someone submits a restore footprint — different remedy, same
+ * consequence for a depositor trying to get out.
+ *
+ * Deliberately excluded: `rpc-failover` (our transport, not their vault),
+ * `assembly` (an SDK-side fault), and validation errors, which carry no stage
+ * at all.
+ */
+const REPORTED_BUILD_STAGES = new Set(['simulation', 'restore-required']);
+function validateContractAddress(contractId) {
+    if (!(0, utils_1.isStellarAddress)(contractId) || contractId[0] !== 'C') {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', `Invalid contract address: expected a Stellar contract (C-prefix), got "${contractId}"`);
+    }
+}
+function validateAccountAddress(address, label) {
+    if (!(0, utils_1.isStellarAddress)(address) || address[0] !== 'G') {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', `Invalid ${label} address: expected a Stellar account (G-prefix), got "${address}"`);
+    }
+}
+/**
+ * Build a self-operation Soroban transaction where all address roles
+ * (receiver, from/owner, operator) are set to the same user address.
+ *
+ * Note: This only supports self-operations. If delegated operations
+ * (distinct receiver/owner/operator) are needed in the future,
+ * a separate argument builder will be required.
+ */
+function buildSelfOperationArgs(amount, userAddress) {
+    const userScVal = new stellar_sdk_1.Address(userAddress).toScVal();
+    return [
+        (0, stellar_sdk_1.nativeToScVal)(amount, { type: 'i128' }),
+        userScVal,
+        userScVal,
+        userScVal,
+    ];
+}
+/**
+ * Deposit assets into a Stellar vault (self-deposit).
+ *
+ * Builds an unsigned Soroban transaction invoking the vault's `deposit` function.
+ * All three address roles (receiver, from, operator) are set to senderAddress.
+ *
+ * Contract signature: deposit(assets: i128, receiver: Address, from: Address, operator: Address) -> i128
+ *
+ * @returns Base64-encoded XDR of the unsigned transaction, ready for wallet signing.
+ */
+async function handleStellarDeposit(params) {
+    const { contractId, amount, senderAddress, network, sorobanRpcUrl } = params;
+    validateContractAddress(contractId);
+    validateAccountAddress(senderAddress, 'sender');
+    const config = (0, soroban_1.resolveNetworkConfig)(network, sorobanRpcUrl);
+    const args = buildSelfOperationArgs((0, soroban_1.toBigIntAmount)(amount, 'deposit amount'), senderAddress);
+    return (0, soroban_1.buildSorobanTx)(config, senderAddress, contractId, 'deposit', args);
+}
+/**
+ * Build an unsigned self-redeem Soroban transaction (receiver, owner, and
+ * operator all = `receiverAddress`). Assumes the deployed vault exposes
+ * `redeem(shares: i128, receiver, owner, operator) -> i128`; divergence
+ * surfaces as a generic Soroban simulation error.
+ *
+ * Side effect on failure: when the *vault* cannot serve the redemption — it
+ * rejected the call, or its ledger state needs restoring — the failure is
+ * reported to that vault's curator. Stellar vaults are instant-redeem only, so
+ * this is the curator's only signal that their depositors cannot get out.
+ * Fire-and-forget and deduped; see
+ * {@link reportRedeemFailure} and {@link REPORTED_BUILD_STAGES}.
+ *
+ * Note this includes a caller-caused rejection such as redeeming more shares
+ * than the wallet holds: the contract trapping is what we can observe, and
+ * telling that apart from a vault-side problem needs the vault's error
+ * taxonomy. A bad address, an unfunded account, and an exhausted RPC failover
+ * are excluded — none of those reached the vault.
+ *
+ * @returns Base64-encoded XDR ready for wallet signing; pass the signed
+ *   XDR to {@link submitStellarTransaction}.
+ */
+async function handleStellarRedeem(params) {
+    const { contractId, shares, receiverAddress, network, sorobanRpcUrl } = params;
+    validateContractAddress(contractId);
+    validateAccountAddress(receiverAddress, 'receiver');
+    const config = (0, soroban_1.resolveNetworkConfig)(network, sorobanRpcUrl);
+    // Normalized once and reused for both the invocation and the report: the
+    // caller's string may be any form `BigInt` accepts (`'0x10'`, `' 42 '`), and
+    // relaying that verbatim hands the reporting endpoint something it rejects.
+    const shareAmount = (0, soroban_1.toBigIntAmount)(shares, 'redeem shares');
+    const args = buildSelfOperationArgs(shareAmount, receiverAddress);
+    try {
+        return await (0, soroban_1.buildSorobanTx)(config, receiverAddress, contractId, 'redeem', args);
+    }
+    catch (err) {
+        if (err instanceof core_1.UpshiftSDKError &&
+            REPORTED_BUILD_STAGES.has(String(err.context?.stage))) {
+            (0, curator_alert_1.reportRedeemFailure)({
+                phase: 'simulation',
+                chain: 'stellar',
+                network,
+                contractId,
+                eoa: receiverAddress,
+                sharesRaw: shareAmount.toString(),
+                error: String(err.message),
+            });
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=actions.js.map

package/lib/adapters/stellar/constants.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Stellar Constants
+ */
+import type { IStellarNetwork } from './types';
+export declare const STELLAR_CHAIN_ID: number;
+export declare const STELLAR_CHAIN: {
+    name: string;
+    chainId: number;
+    explorer: string;
+};
+export declare const SOROBAN_RPC_URLS: Record<IStellarNetwork, string>;
+export declare const NETWORK_PASSPHRASES: Record<IStellarNetwork, string>;
+export declare const STELLAR_FALLBACK_DECIMALS = 7;
+/**
+ * Validity window for a submitted Soroban invocation (seconds).
+ *
+ * This becomes the transaction's `maxTime`. Validators reject a tx whose
+ * `maxTime` has passed (`txTOO_LATE`), so the window must outlast the slowest
+ * realistic sign-then-submit path: hardware wallets, careful manual review,
+ * and institutional approval flows (e.g. Fordefi) that don't sign instantly.
+ * 10 minutes comfortably covers those while staying well inside the Soroban
+ * footprint/ledger-entry TTL, so the simulated footprint can't go stale first.
+ *
+ * The window is anchored to the *network* clock (see `getNetworkCloseTime` in
+ * soroban.ts), not the signer's `Date.now()`, so a skewed device clock can't
+ * make the deadline expire early.
+ */
+export declare const TX_TIMEOUT_SECONDS = 600;
+/** Timeout for read-only Soroban simulation queries (seconds). */
+export declare const QUERY_TIMEOUT_SECONDS = 10;
+/**
+ * Max fee ceiling in stroops (1_000_000 stroops = 0.1 XLM).
+ * assembleTransaction adjusts to the actual fee from simulation.
+ */
+export declare const MAX_FEE_STROOPS = "1000000";
+/** Initial confirmation-poll interval (ms). Grows up to {@link POLL_INTERVAL_MAX_MS}. */
+export declare const POLL_INTERVAL_MS = 2000;
+/** Cap for the backed-off confirmation-poll interval (ms). */
+export declare const POLL_INTERVAL_MAX_MS = 8000;
+/** Multiplier applied to the poll interval after each NOT_FOUND poll. */
+export declare const POLL_INTERVAL_BACKOFF = 1.5;
+/** Maximum number of polling attempts before timeout. */
+export declare const MAX_POLL_ATTEMPTS = 30;