/api/transactions/export

Description

The `/api/transactions/export` endpoint exports CloudCoins from a specified wallet's Bank and Fracked folders to a destination folder (typically "Export"). Exported coins can be shared with others or transferred to a different wallet.

Backward Compatibility: If no wallet_path parameter is provided, the endpoint uses the active wallet. This ensures existing integrations continue to work without modification.

The endpoint will select coins from available authenticated (Bank) and partially-authenticated (Fracked) coins to meet the requested amount. Coins are copied, not moved, so they remain in the original folders after export.

Parameters

All parameters are passed as URL query parameters.

Response

Returns a JSON object with export operation results.

Future Implementation Properties

When fully implemented, the response will also include:

{
  "status": "success",
  "operation": "export",
  "amount": 100,
  "destination": "Export",
  "wallet_path": "C:\\MyWallets\\Default",
  "message": "Export endpoint - implementation pending",
  "exported": 0
}

{
  "status": "success",
  "operation": "export",
  "amount": 100,
  "destination": "Export",
  "wallet_path": "C:\\MyWallets\\Default",
  "exported": 2,
  "exported_value": 100,
  "filename": "export_100cc_2025-01-31_15-30-45.stack",
  "file_path": "C:\\MyWallets\\Default\\Export\\export_100cc_2025-01-31_15-30-45.stack",
  "transaction_id": "2025-01-31_15-30-45",
  "message": "Successfully exported 100 CloudCoins (2 coins) to Export folder"
}

Error Responses

{
  "status": "error",
  "operation": "export",
  "error_code": 400,
  "message": "Invalid amount parameter"
}

Examples

const API_HOST = 'http://localhost:8080';

// Export coins from active wallet (backward compatible)
async function exportCoins(amount, destination = 'Export', walletPath = null) {
    try {
        const params = new URLSearchParams({
            amount: amount,
            destination: destination
        });

        // Add wallet_path if specified (enables exporting from non-active wallets)
        if (walletPath) {
            params.append('wallet_path', walletPath);
        }

        const response = await fetch(`${API_HOST}/api/transactions/export?${params}`);
        const result = await response.json();

        if (result.status === 'success') {
            console.log(`Export initiated: ${result.amount} coins`);
            console.log(`Destination: ${result.destination}`);
            console.log(`Wallet: ${result.wallet_path}`);
            console.log(`Message: ${result.message}`);

            // When fully implemented:
            // console.log(`Exported ${result.exported} coins worth ${result.exported_value} units`);
            // console.log(`File: ${result.filename}`);
        } else {
            console.error('Export failed:', result.message);
        }

        return result;
    } catch (error) {
        console.error('Error exporting coins:', error);
        throw error;
    }
}

// Example 1: Export from active wallet (backward compatible)
await exportCoins(100, 'Export');

// Example 2: Export from active wallet with custom destination
await exportCoins(250, 'Backup');

// Example 3: Export from non-active wallet (new functionality)
await exportCoins(50, 'Export', 'C:\\Wallets\\MyWallet');

// Example 4: Export from non-active wallet with custom destination
await exportCoins(500, 'Shared', 'Wallets/ArchiveWallet');

package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "net/url"
)

const ApiHost = "http://localhost:8080"

type ExportResponse struct {
    Status      string `json:"status"`
    Operation   string `json:"operation"`
    Amount      int    `json:"amount"`
    Destination string `json:"destination"`
    WalletPath  string `json:"wallet_path"`
    Message     string `json:"message"`
    Exported    int    `json:"exported"`

    // Future implementation fields
    ExportedValue int    `json:"exported_value,omitempty"`
    Filename      string `json:"filename,omitempty"`
    FilePath      string `json:"file_path,omitempty"`
    TransactionID string `json:"transaction_id,omitempty"`
}

func exportCoins(amount int, destination string, walletPath string) (*ExportResponse, error) {
    // Build URL with parameters
    params := url.Values{}
    params.Add("amount", fmt.Sprintf("%d", amount))
    params.Add("destination", destination)

    // Add wallet_path only if specified (maintains backward compatibility)
    if walletPath != "" {
        params.Add("wallet_path", walletPath)
    }

    url := fmt.Sprintf("%s/api/transactions/export?%s", ApiHost, params.Encode())

    resp, err := http.Get(url)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        return nil, err
    }

    var result ExportResponse
    if err := json.Unmarshal(body, &result); err != nil {
        return nil, err
    }

    return &result, nil
}

func main() {
    // Example 1: Export from active wallet (backward compatible)
    result1, err := exportCoins(100, "Export", "")
    if err != nil {
        panic(err)
    }
    fmt.Println("Example 1: Active wallet export")
    fmt.Printf("  Wallet: %s\n", result1.WalletPath)
    fmt.Printf("  Amount: %d\n", result1.Amount)
    fmt.Printf("  Destination: %s\n\n", result1.Destination)

    // Example 2: Export from non-active wallet
    result2, err := exportCoins(50, "Export", "C:\\Wallets\\MyWallet")
    if err != nil {
        panic(err)
    }
    fmt.Println("Example 2: Non-active wallet export")
    fmt.Printf("  Wallet: %s\n", result2.WalletPath)
    fmt.Printf("  Amount: %d\n", result2.Amount)
    fmt.Printf("  Destination: %s\n\n", result2.Destination)

    // Example 3: Export from relative path
    result3, err := exportCoins(250, "Backup", "Wallets/ArchiveWallet")
    if err != nil {
        panic(err)
    }
    fmt.Println("Example 3: Relative path wallet export")
    fmt.Printf("  Wallet: %s\n", result3.WalletPath)
    fmt.Printf("  Amount: %d\n", result3.Amount)
    fmt.Printf("  Destination: %s\n", result3.Destination)

    // When fully implemented, also show:
    // if result1.Filename != "" {
    //     fmt.Printf("Export file: %s\n", result1.Filename)
    //     fmt.Printf("Transaction ID: %s\n", result1.TransactionID)
    // }
}

Implementation Details

Current Implementation Status

The endpoint is defined in api_handlers.c (lines 667-690) and currently:

• ✓ Validates the amount parameter (must be present and numeric)
• ✓ Accepts optional destination parameter (defaults to "Export")
• ✓ Accepts optional wallet_path parameter (defaults to active wallet for backward compatibility)
• ✓ Returns structured JSON response with wallet_path information
• ✗ Does NOT read coins from Bank/Fracked folders
• ✗ Does NOT select coins to meet requested amount
• ✗ Does NOT copy coins to destination folder
• ✗ Does NOT generate export filenames
• ✗ Does NOT update transactions.csv

Planned Full Implementation

When fully implemented (via cmd_export_coins() in commands.c), the endpoint will:

1. Resolve the wallet path:
   • If wallet_path is provided: Use that wallet's Bank and Fracked folders
   • If wallet_path is omitted: Use the active wallet (backward compatible)
   • Support both absolute paths (e.g., C:\Wallets\MyWallet) and relative paths
2. Read all coins from the specified wallet's Bank and Fracked folders
3. Select coins whose total value meets or exceeds the requested amount
4. Generate a timestamp-based filename (e.g., export_100cc_2025-01-31_15-30-45.stack)
5. Copy selected coins to the destination folder within the specified wallet
6. Create binary format (.stack) or JSON format files based on configuration
7. Log the transaction in transactions.csv with:
   • Transaction ID (timestamp)
   • Operation type ("export")
   • Wallet path used
   • Amount requested vs amount exported
   • Number of coins exported
   • Destination folder path
8. Return detailed results including exported coin count, file paths, and wallet path used

Coin Selection Algorithm

The system will use a denomination-based selection strategy:

• Prefer larger denominations first to minimize coin count
• Include fracked coins if needed to meet the amount
• May export slightly more than requested if exact change isn't available

Backward Compatibility

Migration Path

If you have existing code, you can gradually adopt the wallet_path parameter:

// Old code (still works without any changes)
const result1 = await fetch('http://localhost:8080/api/transactions/export?amount=100');

// New code with wallet_path support
const result2 = await fetch('http://localhost:8080/api/transactions/export?amount=100&wallet_path=C%3A%5CWallets%5CArchive');

// Response always includes wallet_path (showing which wallet was used)
// Old code: wallet_path will show the active wallet
// New code: wallet_path will show the specified wallet

Workflow Example

File Format Information

When fully implemented, exported files will use CloudCoin Version 3, File Format 9:

• File extension: .stack (binary format) or .json (JSON format)
• File header: 32 bytes containing format version, coin ID, encryption type, and coin count
• Per-coin data: 407 bytes (7-byte header + 400-byte body with 25 Authenticity Numbers)
• Encryption: Optional AES-128-CTR or AES-256-CTR encryption