/api/coins/fix

Description

The /api/coins/fix endpoint implements an automatic healing workflow for coins in the Fracked folder. Fracked coins are those that have 13-24 successful authentications (out of 25 RAIDA servers), meaning they're authentic but have some failing RAIDAs. The Fix operation uses a ticket-based authentication protocol to convert failing RAIDAs to passing status.

The healing process uses two RAIDA commands executed in sequence:

• Get Ticket (0x0228): Collects authentication tickets from passing RAIDAs
• Fix (0x0250): Presents tickets to failing RAIDAs to update their databases

Two-Phase RAIDA Protocol

Phase 1: Get Ticket (0x0228)

For each coin in the Fracked folder, the system identifies all RAIDAs with 'p' (pass) status and requests authentication tickets.

Get Ticket Request Format:
Challenge(16 bytes)
+ [DN(1) + SN(4) + AN(16)] × N coins
+ 3E3E (2-byte terminator)

Get Ticket Response Format:
- ALL_PASS (241): Ticket(4) + 3E3E(2)
- ALL_FAIL (242): 3E3E(2)
- MIXED (243): Bitfield(N) + Ticket(4) + 3E3E(2)

Ticket Characteristics:

• 4-byte random token generated by passing RAIDAs
• Valid for 1 minute from generation
• Each passing RAIDA provides one ticket per coin
• Up to 24 tickets can be collected per coin (one per passing RAIDA)

Phase 2: Fix (0x0250)

Collected tickets are sent to failing RAIDAs for verification and database updates.

Fix Request Format:
Challenge(16 bytes)
+ [DN(1) + SN(4) + Ticket(4)] × N coins
+ 3E3E (2-byte terminator)

Fix Response Format:
- ALL_PASS (241): 3E3E(2) - All coins fixed
- ALL_FAIL (242): 3E3E(2) - All coins rejected
- MIXED (243): Bitfield(N) + 3E3E(2) - Some fixed

Fix Process:

1. Failing RAIDA receives tickets from passing RAIDAs
2. RAIDA verifies tickets with issuing RAIDAs (cross-validation)
3. If 13+ valid tickets received: RAIDA updates its database and returns 'p'
4. If fewer than 13 tickets or verification fails: Returns error or 'f'

Iterative Healing Workflow

The Fix operation runs iteratively to maximize healing success:

Healing Workflow:
1. Read all coins from Fracked folder
2. For each round (max 10):
   a. Identify RAIDAs needing fixing (non-'p' status)
   b. Identify RAIDAs that can provide tickets ('p' status)
   c. Execute Phase 1: Get Ticket (parallel on all 25 RAIDAs)
   d. Collect tickets (require 13+ per coin)
   e. Execute Phase 2: Fix (parallel on all 25 RAIDAs)
   f. Update POWN strings based on results
   g. If no changes from previous round: Stop
3. Run Grade command to sort coins to Bank/Fracked/Counterfeit
4. Generate receipt file

Parameters

This endpoint does not require any parameters. It automatically operates on all coins in the Fracked folder of the active wallet.

Response

Returns a JSON object with the healing operation results.

{
  "status": "success",
  "operation": "coins-fix",
  "message": "Fix operation completed",
  "wallet": "Default",
  "note": "Fracked coins healed using Get Ticket + Fix protocol"
}

{
  "error": "No active wallet",
  "status": 400
}

{
  "error": "Fix operation failed",
  "status": 500
}

Healing Success Criteria

After healing completes, coins are automatically sorted to the appropriate folder based on their final POWN status:

POWN String Grading:
- 25 'p' (perfect)   → Bank (fully authenticated)
- 13-24 'p'          → Fracked (partial authentication)
- 0-12 'p'           → Counterfeit (failed authentication)

Healing Outcomes:
- Success: 13 'p' → 25 'p' (Fracked → Bank)
- Partial: 13 'p' → 20 'p' (Fracked → Fracked, improved)
- Failure: 13 'p' → 10 'p' (Fracked → Counterfeit, degraded)

Receipt File Generation

The Fix operation generates a detailed receipt file in the wallet's Receipts folder.

Receipt Format: YYYY-MM-DD_HH-MM-SS.fix.txt

=== Receipt ===
Type: Fix Fracked Coins
Date: 2025-01-31 15:30:45
Task ID: Jan-31-25_03-30-45-PM

Summary:
- Total coins processed: 5
- Fully healed (25/25): 3
- Partially healed (13-24/25): 1
- Failed healing (0-12/25): 1

Coin Results:
SN 12345 (250): ppppppppppppppppppppppppp (25/25 Pass - Moved to Bank)
SN 67890 (100): pppppppppppppppppnnnpppppp (20/25 Pass - Still Fracked)
SN 54321 (25):  ppppppppppffffff (8/25 Pass - Moved to Counterfeit)
...

Examples

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

async function fixFrackedCoins() {
    try {
        console.log('Starting Fix operation on Fracked folder...');
        const response = await fetch(`${API_HOST}/api/coins/fix`);
        const result = await response.json();

        if (result.status === 'success') {
            console.log('Fix completed successfully');
            console.log(`Wallet: ${result.wallet}`);
            console.log(`Note: ${result.note}`);
            console.log('\nCheck wallet Receipts folder for detailed results');
        } else {
            console.error('Fix failed:', result.error);
        }
    } catch (error) {
        console.error('Error during Fix operation:', error);
    }
}

// Execute fix
fixFrackedCoins();

# Fix all fracked coins in active wallet
curl -X GET "http://localhost:8080/api/coins/fix"

# Fix and pretty-print output
curl -X GET "http://localhost:8080/api/coins/fix" | json_pp

package main

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

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

type FixResponse struct {
    Status    string `json:"status"`
    Operation string `json:"operation"`
    Message   string `json:"message"`
    Wallet    string `json:"wallet"`
    Note      string `json:"note"`
}

func fixFrackedCoins() error {
    fmt.Println("Starting Fix operation on Fracked folder...")

    resp, err := http.Get(fmt.Sprintf("%s/api/coins/fix", ApiHost))
    if err != nil {
        return fmt.Errorf("request failed: %v", err)
    }
    defer resp.Body.Close()

    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        return fmt.Errorf("failed to read response: %v", err)
    }

    var result FixResponse
    if err := json.Unmarshal(body, &result); err != nil {
        return fmt.Errorf("failed to parse response: %v", err)
    }

    if result.Status == "success" {
        fmt.Println("Fix completed successfully")
        fmt.Printf("Wallet: %s\n", result.Wallet)
        fmt.Printf("Note: %s\n", result.Note)
        fmt.Println("\nCheck wallet Receipts folder for detailed results")
        return nil
    }

    return fmt.Errorf("fix failed: %s", result.Message)
}

func main() {
    if err := fixFrackedCoins(); err != nil {
        panic(err)
    }
}

Important Considerations

Troubleshooting

No Tickets Available

If the Fix operation reports "No ticket sources available":

• Check that coins have at least one 'p' (pass) status RAIDA
• Run /api/coins/authenticate to re-authenticate coins
• Verify RAIDA network connectivity with /api/program/echo

Coins Still Fracked After Fix

Some coins may remain fracked after healing:

• Insufficient tickets collected (fewer than 13 per failing RAIDA)
• Network issues preventing ticket verification
• Some RAIDAs may be offline or unreachable
• Run Fix operation again - may heal more coins in subsequent rounds

Coins Moved to Counterfeit

If coins move from Fracked to Counterfeit folder:

• Coins fell below 13 'p' status during Fix operation
• Likely genuine coins with severe network issues
• Try authenticating again during better network conditions
• Contact RAIDA administrators if persistent