/api/coins/break

Description

The `/api/coins/break` endpoint will break a larger denomination coin into smaller denominations. For example, breaking a 100-value coin into four 25-value coins, or a 1000-value coin into ten 100-value coins.

When fully implemented, this endpoint will:

1. Select a coin with the specified denomination from the Bank folder
2. Request available serial numbers from RAIDA for the child coins
3. Send a Break command (0x095c) to all 25 RAIDA servers with:
   • Original coin's serial number, denomination, and authenticity numbers
   • Target denominations for the child coins
   • New serial numbers for the child coins
4. RAIDA destroys the original coin and creates the child coins
5. Download the child coins with their new authenticity numbers
6. Save the child coins to the Bank folder

Parameters

This endpoint requires one query parameter:

Response

Returns a JSON object indicating the break operation status (currently parameter validation only).

{
  "status": "success",
  "operation": "coins-break",
  "message": "Break coin endpoint - parameter-based implementation pending",
  "wallet": "Default",
  "denomination": 3,
  "value": 100,
  "note": "Usually called internally by other processes - needs cmd_break_coin() integration"
}

{
  "status": "error",
  "operation": "coins-break",
  "message": "No active wallet. Please load a wallet first using /api/wallet/load"
}

{
  "status": "error",
  "operation": "coins-break",
  "message": "Missing required parameter: 'denomination'"
}

{
  "status": "error",
  "operation": "coins-break",
  "message": "Invalid denomination value. Must be 0-10"
}

Break Examples

Common denomination breaking scenarios:

Examples

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

async function breakCoin(denomination) {
    try {
        const response = await fetch(
            `${API_HOST}/api/coins/break?denomination=${denomination}`
        );
        const result = await response.json();

        if (result.status === 'success') {
            console.log('Break validated successfully');
            console.log(`Denomination: ${result.denomination} (value: ${result.value})`);
            console.log(`Wallet: ${result.wallet}`);
            console.log(`Note: ${result.note}`);
        } else {
            console.error('Break failed:', result.message);
        }

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

// Example: Break a 100-value coin (denomination code 3)
breakCoin(3);

// Example: Break a 1000-value coin (denomination code 5)
breakCoin(5);

# Break a 100-value coin (denomination code 3)
curl -X GET "http://localhost:8080/api/coins/break?denomination=3"

# Break a 1000-value coin (denomination code 5)
curl -X GET "http://localhost:8080/api/coins/break?denomination=5"

# Break a 250-value coin (denomination code 4)
curl -X GET "http://localhost:8080/api/coins/break?denomination=4"

package main

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

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

type BreakResponse struct {
    Status       string `json:"status"`
    Operation    string `json:"operation"`
    Message      string `json:"message"`
    Wallet       string `json:"wallet,omitempty"`
    Denomination int    `json:"denomination,omitempty"`
    Value        int    `json:"value,omitempty"`
    Note         string `json:"note,omitempty"`
}

func breakCoin(denomination int) (*BreakResponse, error) {
    url := fmt.Sprintf("%s/api/coins/break?denomination=%d", ApiHost, denomination)

    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 BreakResponse
    if err := json.Unmarshal(body, &result); err != nil {
        return nil, err
    }

    return &result, nil
}

func main() {
    // Break a 100-value coin (denomination code 3)
    result, err := breakCoin(3)
    if err != nil {
        panic(err)
    }

    if result.Status == "success" {
        fmt.Printf("Break validated successfully\n")
        fmt.Printf("Denomination: %d (value: %d)\n", result.Denomination, result.Value)
        fmt.Printf("Wallet: %s\n", result.Wallet)
        fmt.Printf("Note: %s\n", result.Note)
    } else {
        fmt.Printf("Break failed: %s\n", result.Message)
    }
}

Denomination Reference

Complete mapping of denomination codes to actual values:

Future Implementation

When fully implemented, this endpoint will integrate with cmd_break_coin() to:

• Accept denomination parameter from API request
• Select an appropriate coin from the Bank folder
• Communicate with RAIDA using the Break protocol (0x095c)
• Handle multi-threaded RAIDA requests for 20-25x performance improvement
• Create transaction receipts in the Receipts folder
• Update wallet balance and coin files
• Return detailed results including child coin serial numbers