upshift-finance 1.0.0

package/lib/adapters/solana/vault.actions.js

@@ -0,0 +1,379 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeSolanaError = describeSolanaError;
+exports.handleSolanaDeposit = handleSolanaDeposit;
+exports.handleSolanaRedeem = handleSolanaRedeem;
+const anchor_1 = require("@coral-xyz/anchor");
+const web3_js_1 = require("@solana/web3.js");
+const spl_token_1 = require("@solana/spl-token");
+const constants_1 = require("./constants");
+const utils_1 = require("./utils");
+const core_1 = require("../../core");
+/**
+ * User-facing fallback for a throwable that carries no extractable reason.
+ * Surfaces as e.g. `"Solana deposit failed: please try again"` — actionable,
+ * and without telling the user we couldn't classify the failure.
+ */
+const REASONLESS_SOLANA_ERROR = 'please try again';
+/**
+ * Extract a human- and machine-readable reason from a thrown Solana/Anchor
+ * error.
+ *
+ * Anchor's {@link https://github.com/coral-xyz/anchor `ProgramError`} calls
+ * `super()` with no argument, so its `.message` is the empty string by
+ * construction — the real reason lives on `.msg`/`.code` (and `.toString()`).
+ * `AnchorError` puts it on `.error.errorMessage` / `.error.errorCode.number`.
+ * Reading `.message` directly (as this file used to) therefore rendered
+ * `"Solana deposit failed: "` for every recognized on-chain revert — dropping
+ * the numeric code the team needs to tell "Vault is paused" from
+ * "Insufficient amount" from an account-constraint violation.
+ *
+ * When no reason can be extracted, returns an actionable, user-facing fallback
+ * rather than an "unknown error" admission — the raw throwable is still
+ * preserved on the wrapped error's `cause` and in telemetry for diagnosis.
+ */
+function describeSolanaError(e) {
+    if (!(e instanceof Error))
+        return REASONLESS_SOLANA_ERROR;
+    const anchor = e;
+    const reason = anchor.error?.errorMessage ?? anchor.msg ?? '';
+    const code = anchor.error?.errorCode?.number ?? anchor.code;
+    if (reason)
+        return code === undefined ? reason : `${reason} (code ${code})`;
+    // SendTransactionError / generic Error carry a non-empty `.message`.
+    if (e.message)
+        return e.message;
+    // Last resort: a subclass may override `toString()` (never the empty string).
+    const str = e.toString();
+    return str && str !== e.name && str !== `${e.name}: `
+        ? str
+        : REASONLESS_SOLANA_ERROR;
+}
+/**
+ * Deposit funds into a Solana August vault and mint share tokens.
+ *
+ * @param depositAmount  `bigint` is treated as raw on-chain units (preferred
+ *   — no JS-float round-trip). `number` is treated as a UI amount and
+ *   scaled by the deposit mint's decimals via {@link uiAmountToRawBn}.
+ * @throws AugustValidationError on missing wallet/programId or invalid amount.
+ * @remarks The on-chain `deposit` instruction has no `min_shares_out`
+ *   parameter; slippage cannot be enforced on-chain until the program ships
+ *   that argument.
+ */
+async function handleSolanaDeposit({ provider, connection, network = constants_1.fallbackNetwork, vaultProgramId, vaultAddress, depositAmount, publicKey, sendTransaction, idl, }) {
+    try {
+        if (!publicKey)
+            throw new core_1.AugustValidationError('INVALID_INPUT', 'handleSolanaDeposit: wallet not connected');
+        if (depositAmount === undefined ||
+            depositAmount === null ||
+            (typeof depositAmount === 'bigint' && depositAmount <= 0n) ||
+            (typeof depositAmount === 'number' && !(depositAmount > 0)))
+            throw new core_1.AugustValidationError('INVALID_INPUT', 'handleSolanaDeposit: depositAmount is required and must be > 0');
+        if (!vaultProgramId)
+            throw new core_1.AugustValidationError('INVALID_INPUT', 'handleSolanaDeposit: vaultProgramId is required');
+        const { depositMint, shareMint, vaultVersion } = await utils_1.SolanaUtils.getVaultMints({
+            network,
+            connection,
+            vaultProgramId,
+            vaultAddress,
+            idl,
+        });
+        if (!depositMint || !shareMint) {
+            throw new Error('Failed to read vault mints from on-chain state');
+        }
+        const _vaultProgramId = new web3_js_1.PublicKey(vaultProgramId);
+        const _publicKey = new web3_js_1.PublicKey(publicKey);
+        const _depositMint = new web3_js_1.PublicKey(depositMint);
+        const program = utils_1.SolanaUtils.getProgram({
+            provider,
+            idl,
+            programId: _vaultProgramId.toBase58(),
+        });
+        core_1.Logger.log.info('handleSolanaDeposit', 'Program', program);
+        const vaultStatePda = vaultAddress
+            ? new web3_js_1.PublicKey(vaultAddress)
+            : utils_1.SolanaUtils.deriveVaultStatePda(_vaultProgramId);
+        core_1.Logger.log.info('handleSolanaDeposit', 'Vault state PDA', vaultStatePda.toBase58());
+        const vaultTokenAtaPda = utils_1.SolanaUtils.deriveVaultTokenAtaPda(_vaultProgramId, _depositMint, vaultVersion);
+        core_1.Logger.log.info('handleSolanaDeposit', 'Vault token ATA PDA', vaultTokenAtaPda.toBase58());
+        // Use on-chain share mint from vault state instead of deriving a PDA,
+        // since PDA derivation assumes one share mint per program (single-vault only).
+        const shareMintAddr = new web3_js_1.PublicKey(shareMint);
+        core_1.Logger.log.info('handleSolanaDeposit', 'Share mint', shareMintAddr.toBase58());
+        // Get mint info to handle decimals
+        const mintInfo = await connection.getParsedAccountInfo(_depositMint);
+        if (!mintInfo.value) {
+            throw new Error('Could not fetch mint info');
+        }
+        const { decimals } = mintInfo.value.data.parsed.info;
+        let depositAmountRaw;
+        if (typeof depositAmount === 'bigint') {
+            depositAmountRaw = new anchor_1.BN(depositAmount.toString());
+        }
+        else {
+            if (isNaN(depositAmount)) {
+                throw new core_1.AugustValidationError('INVALID_INPUT', 'Please enter a valid number for the deposit amount');
+            }
+            if (depositAmount <= 0) {
+                throw new core_1.AugustValidationError('INVALID_INPUT', 'Deposit amount must be greater than 0');
+            }
+            depositAmountRaw = (0, utils_1.uiAmountToRawBn)(depositAmount, decimals);
+        }
+        // Find user's token accounts
+        const userTokenAccounts = await connection.getParsedTokenAccountsByOwner(_publicKey, {
+            mint: _depositMint,
+        });
+        core_1.Logger.log.info('handleSolanaDeposit', 'User token accounts', userTokenAccounts);
+        const userShareAccounts = await connection.getParsedTokenAccountsByOwner(_publicKey, {
+            mint: shareMintAddr,
+        });
+        core_1.Logger.log.info('handleSolanaDeposit', 'User share accounts', userShareAccounts);
+        if (userTokenAccounts.value.length === 0) {
+            throw new core_1.AugustValidationError('INVALID_INPUT', 'No token account found for deposit mint. Please create a token account first.');
+        }
+        let senderShareAccount;
+        if (userShareAccounts.value.length === 0) {
+            core_1.Logger.log.info('handleSolanaDeposit', 'Creating share account');
+            // Create share account if it doesn't exist
+            senderShareAccount = await (0, spl_token_1.getAssociatedTokenAddress)(shareMintAddr, _publicKey);
+            core_1.Logger.log.info('handleSolanaDeposit', 'Sender share account', senderShareAccount.toBase58());
+            // Create the associated token account
+            const createAtaIx = (0, spl_token_1.createAssociatedTokenAccountInstruction)(_publicKey, // payer
+            senderShareAccount, // associated token account
+            _publicKey, // owner
+            shareMintAddr);
+            core_1.Logger.log.info('handleSolanaDeposit', 'Create ATA Ix', createAtaIx.programId.toBase58());
+            const transaction = new web3_js_1.Transaction().add(createAtaIx);
+            const signature = await sendTransaction(transaction, connection);
+            core_1.Logger.log.info('handleSolanaDeposit', 'Created share account:', signature.toString());
+        }
+        else {
+            senderShareAccount = userShareAccounts.value[0]?.pubkey;
+        }
+        const senderTokenAccount = userTokenAccounts.value[0]?.pubkey;
+        core_1.Logger.log.info('handleSolanaDeposit', 'Sender token account', senderTokenAccount);
+        core_1.Logger.log.info('handleSolanaDeposit', '\n\nDeposit TX Params:\n');
+        core_1.Logger.log.info('handleSolanaDeposit', 'Program', depositAmountRaw);
+        core_1.Logger.log.info('handleSolanaDeposit', 'Vault state PDA', vaultStatePda.toBase58());
+        core_1.Logger.log.info('handleSolanaDeposit', 'Vault token ATA PDA', vaultTokenAtaPda.toBase58());
+        core_1.Logger.log.info('handleSolanaDeposit', 'Sender token account', senderTokenAccount?.toBase58());
+        core_1.Logger.log.info('handleSolanaDeposit', 'Sender share account', senderShareAccount?.toBase58());
+        core_1.Logger.log.info('handleSolanaDeposit', 'Share mint', shareMintAddr.toBase58());
+        core_1.Logger.log.info('handleSolanaDeposit', 'Deposit mint', _depositMint?.toBase58());
+        core_1.Logger.log.info('handleSolanaDeposit', 'Signer', _publicKey.toBase58());
+        // Get a fresh blockhash to avoid "Blockhash not found" errors
+        const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash('confirmed');
+        // TODO(slippage): pass `min_shares_out` here when the program ships it.
+        const tx = await program.methods
+            .deposit(depositAmountRaw)
+            .accounts({
+            vaultState: vaultStatePda,
+            vaultTokenAta: vaultTokenAtaPda,
+            senderTokenAccount,
+            senderShareAccount,
+            shareMint: shareMintAddr,
+            depositMint: depositMint,
+            signer: publicKey,
+            tokenProgram: spl_token_1.TOKEN_PROGRAM_ID,
+        })
+            .rpc({
+            skipPreflight: false,
+            preflightCommitment: 'confirmed',
+        });
+        core_1.Logger.log.info('handleSolanaDeposit', 'Deposit successful:', tx);
+        // Wait for confirmation with the blockhash we used
+        await connection.confirmTransaction({
+            signature: tx,
+            blockhash,
+            lastValidBlockHeight,
+        }, 'confirmed');
+        return tx;
+    }
+    catch (e) {
+        if (e instanceof core_1.AugustSDKError)
+            throw e;
+        const depositAmountForLog = typeof depositAmount === 'bigint'
+            ? depositAmount.toString()
+            : depositAmount;
+        core_1.Logger.log.error('handleSolanaDeposit', e, {
+            vaultProgramId: String(vaultProgramId),
+            vaultAddress: vaultAddress ? String(vaultAddress) : undefined,
+            depositAmount: depositAmountForLog,
+        });
+        throw new core_1.AugustSDKError('UNKNOWN', `Solana deposit failed: ${describeSolanaError(e)}`, {
+            cause: e,
+            context: {
+                vaultProgramId: String(vaultProgramId),
+                vaultAddress: vaultAddress ? String(vaultAddress) : undefined,
+                depositAmount: depositAmountForLog,
+            },
+        });
+    }
+}
+/**
+ * Redeem vault shares back into the underlying mint on a Solana August vault.
+ *
+ * @param redeemShares  `bigint` is treated as raw share-token units;
+ *   `number` is treated as a UI amount. See {@link handleSolanaDeposit} for
+ *   the same caveat about the missing on-chain slippage guard.
+ * @throws AugustValidationError on missing wallet/programId or invalid amount.
+ */
+async function handleSolanaRedeem({ provider, connection, vaultProgramId, vaultAddress, publicKey, redeemShares, sendTransaction, idl, }) {
+    try {
+        if (!publicKey)
+            throw new core_1.AugustValidationError('INVALID_INPUT', 'handleSolanaRedeem: wallet not connected');
+        if (redeemShares === undefined ||
+            redeemShares === null ||
+            (typeof redeemShares === 'bigint' && redeemShares <= 0n) ||
+            (typeof redeemShares === 'number' && !(redeemShares > 0)))
+            throw new core_1.AugustValidationError('INVALID_INPUT', 'handleSolanaRedeem: redeemShares is required and must be > 0');
+        if (!vaultProgramId)
+            throw new core_1.AugustValidationError('INVALID_INPUT', 'handleSolanaRedeem: vaultProgramId is required');
+        const { depositMint, shareMint, vaultVersion } = await utils_1.SolanaUtils.getVaultMints({
+            network: provider.connection.rpcEndpoint.includes('devnet')
+                ? 'devnet'
+                : 'mainnet-beta',
+            connection,
+            vaultProgramId,
+            vaultAddress,
+            idl,
+        });
+        if (!depositMint || !shareMint) {
+            throw new Error('Failed to read vault mints from on-chain state');
+        }
+        const _vaultProgramId = new web3_js_1.PublicKey(vaultProgramId);
+        const _depositMint = new web3_js_1.PublicKey(depositMint);
+        const _publicKey = new web3_js_1.PublicKey(publicKey);
+        const program = utils_1.SolanaUtils.getProgram({
+            provider,
+            idl,
+            programId: _vaultProgramId.toBase58(),
+        });
+        const vaultStatePda = vaultAddress
+            ? new web3_js_1.PublicKey(vaultAddress)
+            : utils_1.SolanaUtils.deriveVaultStatePda(_vaultProgramId);
+        const vaultTokenAtaPda = utils_1.SolanaUtils.deriveVaultTokenAtaPda(_vaultProgramId, _depositMint, vaultVersion);
+        // Use on-chain share mint from vault state instead of deriving a PDA,
+        // since PDA derivation assumes one share mint per program (single-vault only).
+        const shareMintAddr = new web3_js_1.PublicKey(shareMint);
+        // Get share mint info to handle decimals
+        const shareMintInfo = await connection.getParsedAccountInfo(shareMintAddr);
+        if (!shareMintInfo.value) {
+            throw new Error('Could not fetch share mint info');
+        }
+        const shareDecimals = shareMintInfo.value.data.parsed.info
+            .decimals;
+        let redeemSharesRaw;
+        if (typeof redeemShares === 'bigint') {
+            redeemSharesRaw = new anchor_1.BN(redeemShares.toString());
+        }
+        else {
+            if (isNaN(redeemShares)) {
+                throw new core_1.AugustValidationError('INVALID_INPUT', 'Please enter a valid number for the shares to redeem');
+            }
+            if (redeemShares <= 0) {
+                throw new core_1.AugustValidationError('INVALID_INPUT', 'Shares to redeem must be greater than 0');
+            }
+            redeemSharesRaw = (0, utils_1.uiAmountToRawBn)(redeemShares, shareDecimals);
+        }
+        // Find user's token accounts
+        const userTokenAccounts = await connection.getParsedTokenAccountsByOwner(_publicKey, {
+            mint: _depositMint,
+        });
+        const userShareAccounts = await connection.getParsedTokenAccountsByOwner(_publicKey, {
+            mint: shareMintAddr,
+        });
+        if (userTokenAccounts.value.length === 0) {
+            throw new core_1.AugustValidationError('INVALID_INPUT', 'No token account found for deposit mint. Please create a token account first.');
+        }
+        if (userShareAccounts.value.length === 0) {
+            throw new core_1.AugustValidationError('INVALID_INPUT', 'No share account found. You need to deposit first to get shares before you can redeem.');
+        }
+        const senderTokenAccount = userTokenAccounts?.value[0]?.pubkey;
+        const senderShareAccount = userShareAccounts?.value[0]?.pubkey;
+        // Get the fee recipient from vault state
+        const readOnlyProvider = utils_1.SolanaUtils.getReadOnlyProvider({ connection });
+        const readOnlyProgram = utils_1.SolanaUtils.getProgram({
+            provider: readOnlyProvider,
+            idl,
+            programId: _vaultProgramId.toBase58(),
+        });
+        const vaultStateData = await readOnlyProgram.account.vaultState.fetch(vaultStatePda);
+        // Get the fee recipient's token account
+        const feeRecipientTokenAccount = await (0, spl_token_1.getAssociatedTokenAddress)(_depositMint, vaultStateData.feeRecipient);
+        // Check if the fee recipient token account exists, if not create it
+        const feeRecipientAccountInfo = await connection.getAccountInfo(feeRecipientTokenAccount);
+        if (!feeRecipientAccountInfo) {
+            const createFeeRecipientAtaIx = (0, spl_token_1.createAssociatedTokenAccountInstruction)(_publicKey, // payer (user pays for the account creation)
+            feeRecipientTokenAccount, // associated token account
+            vaultStateData.feeRecipient, // owner (the actual fee recipient)
+            _depositMint);
+            const createAccountTx = new web3_js_1.Transaction().add(createFeeRecipientAtaIx);
+            const createAccountSignature = await sendTransaction(createAccountTx, connection);
+            core_1.Logger.log.info('handleSolanaRedeem', 'Fee recipient token account created:', createAccountSignature);
+            // Wait a moment for the account to be created
+            await new Promise((resolve) => setTimeout(resolve, 1000));
+        }
+        else {
+            core_1.Logger.log.info('handleSolanaRedeem', 'Fee recipient token account already exists');
+        }
+        core_1.Logger.log.info('handleSolanaRedeem', '\n\nRedeem TX Params:\n');
+        core_1.Logger.log.info('handleSolanaRedeem', 'Redeem shares (UI):', redeemShares);
+        core_1.Logger.log.info('handleSolanaRedeem', 'Redeem shares (raw):', redeemSharesRaw);
+        core_1.Logger.log.info('handleSolanaRedeem', 'Share decimals:', shareDecimals);
+        core_1.Logger.log.info('handleSolanaRedeem', 'Vault state PDA:', vaultStatePda.toBase58());
+        core_1.Logger.log.info('handleSolanaRedeem', 'Vault token ATA PDA:', vaultTokenAtaPda.toBase58());
+        core_1.Logger.log.info('handleSolanaRedeem', 'Sender token account:', senderTokenAccount?.toBase58());
+        core_1.Logger.log.info('handleSolanaRedeem', 'Sender share account:', senderShareAccount?.toBase58());
+        core_1.Logger.log.info('handleSolanaRedeem', 'Fee recipient account:', feeRecipientTokenAccount.toBase58());
+        core_1.Logger.log.info('handleSolanaRedeem', 'Share mint:', shareMintAddr.toBase58());
+        core_1.Logger.log.info('handleSolanaRedeem', 'Deposit mint:', _depositMint?.toBase58());
+        core_1.Logger.log.info('handleSolanaRedeem', 'Signer:', _publicKey.toBase58());
+        // Get a fresh blockhash to avoid "Blockhash not found" errors
+        const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash('confirmed');
+        const tx = await program.methods
+            .redeem(redeemSharesRaw)
+            .accounts({
+            vaultState: vaultStatePda,
+            vaultDepositAta: vaultTokenAtaPda,
+            senderTokenAccount,
+            senderShareAccount,
+            feeRecipientAccount: feeRecipientTokenAccount, // The actual fee recipient's token account
+            shareMint: shareMintAddr,
+            depositMint: _depositMint,
+            signer: _publicKey,
+            tokenProgram: spl_token_1.TOKEN_PROGRAM_ID,
+        })
+            .rpc({
+            skipPreflight: false,
+            preflightCommitment: 'confirmed',
+        });
+        core_1.Logger.log.info('handleSolanaRedeem', 'Redeem successful:', tx);
+        // Wait for confirmation with the blockhash we used
+        await connection.confirmTransaction({
+            signature: tx,
+            blockhash,
+            lastValidBlockHeight,
+        }, 'confirmed');
+        return tx;
+    }
+    catch (e) {
+        if (e instanceof core_1.AugustSDKError)
+            throw e;
+        const redeemSharesForLog = typeof redeemShares === 'bigint' ? redeemShares.toString() : redeemShares;
+        core_1.Logger.log.error('handleSolanaRedeem', e, {
+            vaultProgramId: String(vaultProgramId),
+            vaultAddress: vaultAddress ? String(vaultAddress) : undefined,
+            redeemShares: redeemSharesForLog,
+        });
+        throw new core_1.AugustSDKError('UNKNOWN', `Solana redeem failed: ${describeSolanaError(e)}`, {
+            cause: e,
+            context: {
+                vaultProgramId: String(vaultProgramId),
+                vaultAddress: vaultAddress ? String(vaultAddress) : undefined,
+                redeemShares: redeemSharesForLog,
+            },
+        });
+    }
+}
+//# sourceMappingURL=vault.actions.js.map

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

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ *
+ * @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,77 @@
+"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");
+function validateContractAddress(contractId) {
+    if (!(0, utils_1.isStellarAddress)(contractId) || contractId[0] !== 'C') {
+        throw new core_1.AugustValidationError('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.AugustValidationError('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.
+ *
+ * @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);
+    const args = buildSelfOperationArgs((0, soroban_1.toBigIntAmount)(shares, 'redeem shares'), receiverAddress);
+    return (0, soroban_1.buildSorobanTx)(config, receiverAddress, contractId, 'redeem', args);
+}
+//# 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;

package/lib/adapters/stellar/constants.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Stellar Constants
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_POLL_ATTEMPTS = exports.POLL_INTERVAL_BACKOFF = exports.POLL_INTERVAL_MAX_MS = exports.POLL_INTERVAL_MS = exports.MAX_FEE_STROOPS = exports.QUERY_TIMEOUT_SECONDS = exports.TX_TIMEOUT_SECONDS = exports.STELLAR_FALLBACK_DECIMALS = exports.NETWORK_PASSPHRASES = exports.SOROBAN_RPC_URLS = exports.STELLAR_CHAIN = exports.STELLAR_CHAIN_ID = void 0;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const web3_1 = require("../../core/constants/web3");
+// Synthetic chain ID for Stellar, sourced from SPECIAL_CHAINS. See core/constants/web3.ts for all non-EVM chain IDs.
+exports.STELLAR_CHAIN_ID = web3_1.SPECIAL_CHAINS.stellar.chainId;
+exports.STELLAR_CHAIN = web3_1.SPECIAL_CHAINS.stellar;
+exports.SOROBAN_RPC_URLS = {
+    mainnet: 'https://soroban-rpc.mainnet.stellar.gateway.fm',
+    testnet: 'https://soroban-testnet.stellar.org',
+};
+exports.NETWORK_PASSPHRASES = {
+    mainnet: stellar_sdk_1.Networks.PUBLIC,
+    testnet: stellar_sdk_1.Networks.TESTNET,
+};
+// Most Stellar/Soroban tokens use 7 decimal places (matching XLM's 10^7 stroops convention).
+// Used as fallback when deposit_token_decimals is not available from backend metadata.
+exports.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.
+ */
+exports.TX_TIMEOUT_SECONDS = 600;
+/** Timeout for read-only Soroban simulation queries (seconds). */
+exports.QUERY_TIMEOUT_SECONDS = 10;
+/**
+ * Max fee ceiling in stroops (1_000_000 stroops = 0.1 XLM).
+ * assembleTransaction adjusts to the actual fee from simulation.
+ */
+exports.MAX_FEE_STROOPS = '1000000';
+/** Initial confirmation-poll interval (ms). Grows up to {@link POLL_INTERVAL_MAX_MS}. */
+exports.POLL_INTERVAL_MS = 2000;
+/** Cap for the backed-off confirmation-poll interval (ms). */
+exports.POLL_INTERVAL_MAX_MS = 8000;
+/** Multiplier applied to the poll interval after each NOT_FOUND poll. */
+exports.POLL_INTERVAL_BACKOFF = 1.5;
+/** Maximum number of polling attempts before timeout. */
+exports.MAX_POLL_ATTEMPTS = 30;
+//# sourceMappingURL=constants.js.map

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

@@ -0,0 +1,68 @@
+/**
+ * Stellar Vault Getters
+ *
+ * Data fetching for Stellar vaults. Enriches backend metadata with on-chain
+ * total assets, total supply, and share decimals from Soroban RPC. Also
+ * provides user position queries and deposit preview (convertToShares).
+ * Falls back to backend TVL for total assets, zero for total supply, and
+ * STELLAR_FALLBACK_DECIMALS for share decimals when on-chain queries fail.
+ */
+import type { ITokenizedVault, IVault } from '../../types';
+import type { IVaultBaseOptions } from '../../modules/vaults/types';
+import type { IStellarNetwork, IStellarUserPosition } from './types';
+/**
+ * Build a unified IVault from backend + on-chain data for Stellar vaults.
+ * Reads total assets and total supply from the Soroban contract via RPC.
+ * Falls back to backend `latest_reported_tvl` for total assets, or zero
+ * for total supply, when on-chain queries fail.
+ */
+export declare const getStellarVault: (tokenizedVault: ITokenizedVault, options: IVaultBaseOptions) => Promise<IVault>;
+/**
+ * Get user position for a Stellar vault.
+ * Queries the vault contract's balance(address) and decimals() functions via Soroban RPC.
+ *
+ * Returns `{ shares, decimals, decimalsFromFallback }` on success (shares may be
+ * '0' for zero balance), or null when the balance query fails. The two reads are
+ * independent: a `decimals()` failure does NOT null the result — instead
+ * `decimals` falls back to STELLAR_FALLBACK_DECIMALS (7) and
+ * `decimalsFromFallback` is set to `true` so callers can tell a fabricated 7
+ * apart from a genuine 7-decimal vault.
+ *
+ * Why this matters: an ERC4626 offset vault has share decimals = asset + offset
+ * (e.g. 13). A consumer that sizes a redeem trusting a silent fallback 7 would
+ * under-redeem by `10^offset`. Callers that settle a redeem from this position
+ * MUST refuse (surface an error) when `decimalsFromFallback` is `true` rather
+ * than trusting `decimals`. See AUGUST-6381 (follow-up to AUGUST-6380).
+ *
+ * @param vaultAddress - Stellar vault contract ID (C… address)
+ * @param walletAddress - User's Stellar account (G… address); validated upfront
+ * @param network - 'mainnet' | 'testnet' (defaults to 'mainnet')
+ * @param sorobanRpcUrl - Optional override Soroban RPC endpoint (e.g. a keyed
+ *   Alchemy URL); becomes the primary with the SDK's public endpoints kept as
+ *   failover. Omit to use the public endpoints.
+ * @returns The position, or `null` if the balance read failed or was unparseable.
+ * @throws AugustValidationError on an invalid `walletAddress`.
+ * @example
+ * ```ts
+ * const pos = await getStellarUserPosition(vault, wallet, 'mainnet');
+ * if (!pos || pos.decimalsFromFallback) {
+ *   // Refuse to size a redeem — share scale is not authoritatively known.
+ *   throw new Error('Stellar share decimals unresolved');
+ * }
+ * const human = Number(pos.shares) / 10 ** pos.decimals;
+ * ```
+ */
+export declare const getStellarUserPosition: (vaultAddress: string, walletAddress: string, network?: IStellarNetwork, sorobanRpcUrl?: string) => Promise<IStellarUserPosition | null>;
+/**
+ * Query the vault's `convert_to_shares` to preview how many shares a deposit
+ * amount would yield.  Returns the raw share amount as a string, or null on
+ * failure.
+ *
+ * @param vaultAddress  Stellar contract ID (C… address)
+ * @param rawAmount     Deposit amount in the deposit token's smallest unit
+ * @param network       'mainnet' | 'testnet'
+ * @param sorobanRpcUrl - Optional override Soroban RPC endpoint (e.g. a keyed
+ *   Alchemy URL); becomes the primary with the SDK's public endpoints kept as
+ *   failover. Omit to use the public endpoints.
+ */
+export declare const convertToShares: (vaultAddress: string, rawAmount: string, network?: IStellarNetwork, sorobanRpcUrl?: string) => Promise<string | null>;