Beginner Guide

1. HTML Structure     → User interface elements with professional styling
2. External Libraries → Freighter API for wallet integration
3. Configuration     → Centralized CONFIG object with vault and API settings
4. Application State  → Tracks wallet connection and vault transaction status
5. Utility Functions  → Helper functions for UI updates and API calls
6. Core Functions    → Connect, Deposit, Sign, and Send (4 separate steps)

async function connectStellarWallet() {
    // Step 1: Check if Freighter wallet is installed
    const hasFreighter = await freighter.isConnected();
    console.log('Freighter connected:', hasFreighter);

    // Step 2: If not installed, show error message
    if (!hasFreighter.isConnected) {
        alert('Please install the Freighter wallet extension first.');
        return; // Stop function execution
    }

    // Step 3: Request permission to connect
    console.log('Connecting to Freighter...');
    account = await freighter.requestAccess();
    account = account.address; // Extract just the address

    // Step 4: Update the user interface
    connectButton.disabled = true; // Disable connect button
    document.getElementById('account').innerText = `Connected account: ${account}`;
}

async function getVaultInfoAndDeposit() {
    try {
        // Make sure wallet is connected
        if (!appState.connected) {
            updateStatus('❌ Please connect your wallet first!', 'error');
            return;
        }

        // PHASE 1: Get Vault Information
        updateStatus('🔄 Getting vault information...', 'info');

        appState.vaultInfo = await makeAPIRequest(`/vault/${CONFIG.VAULT_ADDRESS}`, null, 'GET');

        updateStatus(`✅ Vault loaded: ${appState.vaultInfo.name}<br />🔄 Building deposit transaction...`, 'info');

        // PHASE 2: Build Deposit Transaction
        const depositRequest = {
            amounts: [CONFIG.DEPOSIT.AMOUNT],    // Amount to deposit (1 XLM)
            caller: appState.walletAddress,      // Who's depositing
            invest: CONFIG.DEPOSIT.INVEST,       // Auto-invest into strategies
            slippageBps: CONFIG.DEPOSIT.SLIPPAGE // Slippage tolerance
        };

        const buildResult = await makeAPIRequest(`/vault/${CONFIG.VAULT_ADDRESS}/deposit`, depositRequest);
        appState.unsignedXdr = buildResult.xdr;

        // Show the unsigned transaction for educational purposes
        ELEMENTS.unsignedXdr.value = buildResult.xdr;
        ELEMENTS.technicalDetails.classList.remove('hidden');

        updateStatus(`✅ Deposit transaction built!<br />⏳ Ready for signing...`, 'info');
        updateButtonStates();
    } catch (error) {
        console.error('Vault deposit process failed:', error);
        updateStatus(`❌ Process failed: ${error.message}`, 'error');
    }
}

async function signTransaction() {
    try {
        // Make sure wallet is connected and we have a transaction to sign
        if (!appState.connected) {
            updateStatus('❌ Please connect your wallet first!', 'error');
            return;
        }

        if (!appState.unsignedXdr) {
            updateStatus('❌ No transaction to sign. Please get a quote first!', 'error');
            return;
        }

        updateStatus('📝 Please approve the transaction in Freighter...', 'info');

        // Sign the transaction using Freighter
        const signResult = await freighterAPI.signTransaction(appState.unsignedXdr, {
            network: CONFIG.NETWORK,
            networkPassphrase: 'Test SDF Network ; September 2015',
            address: appState.walletAddress
        });

        appState.signedTransaction = signResult.signedTxXdr;

        // Show the signed transaction for educational purposes
        ELEMENTS.signedXdr.value = appState.signedTransaction;

        const depositAmount = formatAmount(CONFIG.DEPOSIT.AMOUNT, 7);
        updateStatus(`✅ Transaction signed successfully!<br />📋 Ready to deposit ${depositAmount} XLM into vault`, 'success');
        updateButtonStates();
    } catch (error) {
        console.error('Transaction signing failed:', error);
        updateStatus(`❌ Transaction signing failed: ${error.message}`, 'error');
    }
}

async function sendTransaction() {
    try {
        // Make sure we have a signed transaction
        if (!appState.signedTransaction) {
            updateStatus('❌ No signed transaction available. Please get a quote and sign it first.', 'error');
            return;
        }

        updateStatus('🚀 Broadcasting transaction to Stellar network...', 'info');

        // Send the signed transaction
        const sendRequest = {
            xdr: appState.signedTransaction     // The signed transaction
        };

        const sendResult = await makeAPIRequest('/send', sendRequest);

        // Create link to view transaction on Stellar Expert
        const explorerUrl = `https://stellar.expert/explorer/${CONFIG.NETWORK}/tx/${sendResult.txHash}`;

        // Show success message
        ELEMENTS.transactionLink.innerHTML = `
            <strong>Transaction Hash:</strong> <code>${sendResult.txHash}</code><br />
            <a href="${explorerUrl}" target="_blank" rel="noopener">🔗 View on Stellar Expert</a>
        `;
        ELEMENTS.finalResults.classList.remove('hidden');

        updateStatus('🎉 Vault deposit completed successfully! You now own vault shares (dfTokens). Check the transaction link above.', 'success');

        // Reset state for potential next transaction
        appState.unsignedXdr = null;
        appState.signedTransaction = null;
        appState.currentQuote = null;
        updateButtonStates();

    } catch (error) {
        console.error('Transaction send failed:', error);
        updateStatus(`❌ Transaction failed: ${error.message}`, 'error');
    }
}

🔗 STEP 1: Connect Wallet
User clicks "Connect Freighter Wallet"
   ↓ connectWallet() function
App connects to Freighter wallet ✅
   ↓

💰 STEP 2: Get Vault Info & Build Deposit
User clicks "Deposit into Vault (1 XLM)"
   ↓ getVaultInfoAndDeposit() function
App gets vault info + builds unsigned deposit transaction ✅
   ↓

✍️ STEP 3: Sign Transaction
User clicks "Sign Transaction"
   ↓ signTransaction() function
User approves transaction in Freighter wallet ✅
   ↓

🚀 STEP 4: Send to Network
User clicks "Send Transaction"
   ↓ sendTransaction() function
App broadcasts to Stellar network ✅
   ↓
🎉 VAULT DEPOSIT COMPLETE!