[P6] Implement Wallet API methods (8 endpoints)

[umwelt]

Overview

Implement all Wallet API methods in the TypeScript client to match the ZHTP node's wallet endpoints.

Related to: #17 - Comprehensive API Implementation Guide
Priority: P6 - HIGH (Core financial feature)
Estimated Effort: Medium-Large (6-8 hours)

Background

The ZHTP node has 8 wallet endpoints covering balance queries, transaction history, and fund transfers. The API client likely has some wallet methods already implemented but needs verification and completion.

Required Methods

Balance Methods (2 endpoints)

1. getWalletBalance() ✅ LIKELY EXISTS - NEEDS VERIFICATION

Endpoint: GET /api/v1/wallet/balance

Expected Response:

{
  status: "success",
  balance: 1000000,
  currency: "SOVEREIGN",
  locked: 50000,
  available: 950000
}

Action: Verify implementation matches node response format

2. getWalletBalances() ❓ UNKNOWN

Endpoint: GET /api/v1/wallet/balances

Expected Response (multi-currency):

{
  status: "success",
  balances: [
    {
      currency: "SOVEREIGN",
      balance: 1000000,
      locked: 50000,
      available: 950000
    },
    {
      currency: "BTC",
      balance: 0.5,
      locked: 0,
      available: 0.5
    }
  ]
}

Action: Check if exists, implement if missing

Transaction Methods (4 endpoints)

3. getWalletTransactions() ✅ LIKELY EXISTS - NEEDS VERIFICATION

Endpoint: GET /api/v1/wallet/transactions

Query params: ?limit=10&offset=0&type=all

Expected Response:

{
  status: "success",
  transactions: [
    {
      tx_id: "...",
      type: "send" | "receive" | "stake" | "unstake",
      amount: 1000,
      from: "did:zhtp:...",
      to: "did:zhtp:...",
      timestamp: 1234567890,
      status: "confirmed" | "pending" | "failed",
      fee: 10
    }
  ],
  total: 100,
  limit: 10,
  offset: 0
}

Action: Verify query parameter support and response format

4. getWalletTransaction() ❓ UNKNOWN

Endpoint: GET /api/v1/wallet/transactions/{tx_id}

Expected Response:

{
  status: "success",
  transaction: {
    tx_id: "...",
    type: "send",
    amount: 1000,
    from: "did:zhtp:...",
    to: "did:zhtp:...",
    timestamp: 1234567890,
    status: "confirmed",
    fee: 10,
    block_height: 12345,
    confirmations: 10
  }
}

Action: Check if exists, implement if missing

5. sendWalletTransaction() ✅ LIKELY EXISTS - NEEDS VERIFICATION

Endpoint: POST /api/v1/wallet/send

Request:

{
  to: string, // DID or wallet address
  amount: number,
  currency?: string,
  memo?: string
}

Expected Response:

{
  status: "success",
  tx_id: "...",
  timestamp: 1234567890,
  fee: 10
}

Action: Verify implementation

6. estimateWalletFee() ❌ MISSING

Endpoint: POST /api/v1/wallet/estimate-fee

Request:

{
  to: string,
  amount: number,
  currency?: string,
  priority?: "low" | "medium" | "high"
}

Expected Response:

{
  status: "success",
  estimated_fee: 10,
  estimated_confirmation_time: 60, // seconds
  priority: "medium"
}

Action: Implement new method

Address Methods (2 endpoints)

7. getWalletAddress() ✅ LIKELY EXISTS - NEEDS VERIFICATION

Endpoint: GET /api/v1/wallet/address

Expected Response:

{
  status: "success",
  address: "did:zhtp:...",
  public_key: "...",
  currency: "SOVEREIGN"
}

Action: Verify implementation

8. generateWalletAddress() ❌ MISSING

Endpoint: POST /api/v1/wallet/address/generate

Request:

{
  currency?: string,
  label?: string
}

Expected Response:

{
  status: "success",
  address: "...",
  public_key: "...",
  currency: "SOVEREIGN",
  label: "My new address"
}

Action: Implement new method

Implementation Checklist

Phase 1: Verify Existing Methods

• Verify getWalletBalance() exists and matches format
• Verify getWalletTransactions() supports query parameters
• Verify sendWalletTransaction() supports all fields
• Verify getWalletAddress() implementation

Phase 2: Check Unknown Methods

• Check if getWalletBalances() exists (multi-currency support)
• Check if getWalletTransaction() exists (single tx query)

Phase 3: Implement Missing Methods

• Implement estimateWalletFee() (if missing)
• Implement generateWalletAddress() (if missing)
• Implement any other missing methods found in Phase 2

Phase 4: Testing

• Test balance queries
• Test transaction history with pagination
• Test sending transactions (use testnet!)
• Test fee estimation
• Test address generation
• Test error handling (insufficient funds, invalid address, etc.)

Phase 5: Documentation

• Add JSDoc comments to all methods
• Document transaction types and statuses
• Create usage examples for common flows:
  • Check balance → Estimate fee → Send transaction
  • Query transaction history
  • Generate new address
• Update main README with wallet examples

Files to Modify

• src/core/zhtp-api-methods.ts - Add/verify wallet methods
• src/core/types.ts - Add wallet-related type definitions
• src/core/zhtp-api-client.ts - Export new methods

Success Criteria

• All 8 wallet endpoints have corresponding TypeScript methods
• All methods use /api/v1 paths
• Response types match node implementation
• All methods handle errors properly (insufficient funds, invalid addresses, etc.)
• Full test coverage for wallet functionality
• Documentation complete with usage examples

Security Considerations

• Private Key Safety: Ensure transaction signing happens client-side
• Amount Validation: Validate amounts are positive and within safe integer range
• Address Validation: Validate recipient addresses before sending
• Fee Transparency: Always show fees to users before confirming transactions
• Confirmation: Consider requiring user confirmation for large transactions

Priority Rationale

Wallet functionality is critical for any blockchain application. Users need to be able to:

• Check their balances
• Send and receive funds
• Track transaction history
• Estimate fees before sending

This is a core feature that many other features depend on (marketplace, DAO treasury, staking, etc.).

Dependencies

• Session authentication (already implemented)
• Identity management (already implemented)
• Transaction signing utilities (may need to verify/implement)
• Error handling utilities (already implemented)

Related Issues

• [IMPLEMENTATION GUIDE] Complete ZHTP Node API Endpoint Reference #17 - Parent issue: Complete API Implementation Guide
• Node issue [META] Missing API endpoints - Tracking Issue The-Sovereign-Network#112 (closed - all endpoints implemented)

Testing Notes

IMPORTANT: Use testnet or small amounts when testing transaction functionality! Never test with real funds on mainnet during development.

Consider implementing a "dry run" mode for testing transaction flows without actually broadcasting transactions.