/api/transactions/export

Description

The `/api/transactions/export` endpoint exports CloudCoins from the active 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.

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",
  "message": "Export endpoint - implementation pending",
  "exported": 0
}

{
  "status": "success",
  "operation": "export",
  "amount": 100,
  "destination": "Export",
  "exported": 2,
  "exported_value": 100,
  "filename": "export_100cc_2025-01-31_15-30-45.stack",
  "file_path": "C:\\MyWallet3\\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 100 CloudCoins to default Export folder
async function exportCoins(amount, destination = 'Export') {
    try {
        const params = new URLSearchParams({
            amount: amount,
            destination: destination
        });

        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(`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 usage
exportCoins(100, 'Export');
exportCoins(250, 'Backup');

# Export 100 CloudCoins to default Export folder
curl -X GET "http://localhost:8080/api/transactions/export?amount=100"

# Export 250 CloudCoins to custom destination
curl -X GET "http://localhost:8080/api/transactions/export?amount=250&destination=Backup"

# Export with formatted output
curl -X GET "http://localhost:8080/api/transactions/export?amount=100&destination=Export" | jq .

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"`
    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) (*ExportResponse, error) {
    // Build URL with parameters
    params := url.Values{}
    params.Add("amount", fmt.Sprintf("%d", amount))
    params.Add("destination", destination)

    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() {
    // Export 100 coins to Export folder
    result, err := exportCoins(100, "Export")
    if err != nil {
        panic(err)
    }

    fmt.Printf("Status: %s\n", result.Status)
    fmt.Printf("Amount requested: %d\n", result.Amount)
    fmt.Printf("Destination: %s\n", result.Destination)
    fmt.Printf("Message: %s\n", result.Message)
    fmt.Printf("Coins exported: %d\n", result.Exported)

    // When fully implemented:
    // if result.Filename != "" {
    //     fmt.Printf("Export file: %s\n", result.Filename)
    //     fmt.Printf("Transaction ID: %s\n", result.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")
• ✓ Returns structured JSON response
• ✗ 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. Read all coins from the active wallet's Bank and Fracked folders
2. Select coins whose total value meets or exceeds the requested amount
3. Generate a timestamp-based filename (e.g., export_100cc_2025-01-31_15-30-45.stack)
4. Copy selected coins to the destination folder
5. Create binary format (.stack) or JSON format files based on configuration
6. Log the transaction in transactions.csv with:
   • Transaction ID (timestamp)
   • Operation type ("export")
   • Amount requested vs amount exported
   • Number of coins exported
   • Destination folder path
7. Return detailed results including exported coin count and file paths

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

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