[FRONTEND]: API path inconsistencies between client and node

[umwelt]

Problem

The API client library is using old-style paths without the /api/v1 prefix. While the ZHTP node has added backward-compatible aliases (PR #109), the library should be updated to use the canonical /api/v1 paths.

Current State

The library uses these old paths:

• /mesh/peers
• /node/status
• /blockchain/info
• /dao/proposals
• /dao/vote
• /dao/treasury
• /dao/data
• /dao/delegates
• /wallet/send
• /health

Required Changes

Update src/core/zhtp-api-methods.ts to use /api/v1 prefix for all endpoints:

Current Path	Should Be
/mesh/peers	/api/v1/blockchain/network/peers
/node/status	/api/v1/protocol/info
/blockchain/info	/api/v1/blockchain/status
/dao/proposals	/api/v1/dao/proposals/list
/dao/vote	/api/v1/dao/vote/cast
/dao/treasury	/api/v1/dao/treasury/balance
/dao/data	/api/v1/dao/data
/dao/delegates	/api/v1/dao/delegates
/dao/delegates/register	/api/v1/dao/delegates/register
/dao/delegates/revoke	/api/v1/dao/delegates/revoke
/dao/treasury/history	/api/v1/dao/treasury/history
/dao/proposals/spending	/api/v1/dao/proposals/spending
/wallet/send	/api/v1/wallet/send
/health	/api/v1/protocol/health

Implementation

File: src/core/zhtp-api-methods.ts

Lines to update:

• Line 375: /mesh/peers → /api/v1/blockchain/network/peers
• Line 412: /wallet/send → /api/v1/wallet/send
• Line 422: /dao/proposals → /api/v1/dao/proposals/list
• Line 450: /dao/proposals → /api/v1/dao/proposals (create)
• Line 462: /dao/vote → /api/v1/dao/vote/cast
• Line 470: /dao/treasury → /api/v1/dao/treasury/balance
• Line 479: /dao/data → /api/v1/dao/data
• Line 483: /dao/delegates → /api/v1/dao/delegates
• Line 491: /dao/delegates/register → /api/v1/dao/delegates/register
• Line 499: /dao/delegates/revoke → /api/v1/dao/delegates/revoke
• Line 507: /dao/treasury/history → /api/v1/dao/treasury/history
• Line 511: /dao/proposals/spending → /api/v1/dao/proposals/spending
• Line 575: /blockchain/info → /api/v1/blockchain/status
• Line 579: /network/gas → /api/v1/network/gas
• Line 583: /node/status → /api/v1/protocol/info
• Line 587: /mesh/peers → /api/v1/blockchain/network/peers
• Line 712: /node/status → /api/v1/protocol/info

Benefits

1. Future-proof: Uses canonical versioned API paths
2. Consistency: All endpoints follow same pattern
3. Clarity: Explicit about API version
4. Best practice: Follows REST API versioning conventions

Acceptance Criteria

• All old-style paths updated to /api/v1/* format
• Library builds successfully
• Tests pass (if any)
• No breaking changes to public API surface
• Version bumped appropriately (minor or patch)

Priority

P1 - HIGH - Good practice, but node aliases provide backward compatibility

Related

• Node PR #109: Added backward-compatible path aliases
• Node Issue #112: Missing endpoint implementations

[umwelt]

Status Update

PR #109 in the ZHTP node repository has partially resolved this issue by adding path aliases for backward compatibility.

✅ Fixed in PR #109

The following path aliases were added to the ZHTP node router:

API Client Path	Node Alias Added	Routes To
/mesh/peers	✅	/api/v1/blockchain/network/peers
/node/status	✅	/api/v1/protocol/info
/blockchain/info	✅	/api/v1/blockchain/status
/dao/proposals	✅	/api/v1/dao/proposals/list
/dao/vote	✅	/api/v1/dao/vote/cast
/dao/treasury	✅	/api/v1/dao/treasury/balance

❌ Still Missing Path Aliases

The following endpoints used by the API client library still need aliases on the ZHTP node:

API Client Path	Status	Notes
/network/gas	NOT IMPLEMENTED	Missing endpoint (also tracked in Issue #10)
/dao/data	NO ALIAS	Needs mapping to /api/v1/dao/data
/dao/delegates	NO ALIAS	Needs mapping to /api/v1/dao/delegates
/dao/delegates/register	NO ALIAS	Needs mapping to /api/v1/dao/delegates/register
/dao/delegates/revoke	NO ALIAS	Needs mapping to /api/v1/dao/delegates/revoke
/dao/treasury/history	NO ALIAS	Needs mapping to /api/v1/dao/treasury/history
/dao/proposals/spending	NO ALIAS	Needs mapping to /api/v1/dao/proposals/spending
/wallet/send	NO ALIAS	Needs mapping to /api/v1/wallet/send
/health	NO ALIAS	Needs mapping to /api/v1/health or /api/v1/protocol/health

✅ Already Using Correct Paths

These API client endpoints already use /api/v1 prefix and don't need changes:

• All /api/v1/identity/* endpoints
• All /api/v1/guardian/* endpoints
• All /api/v1/contract/* endpoints
• /api/v1/web4/load
• All /api/v1/zkp/* endpoints

Next Steps

Option A: Complete Node-Side Aliases (Recommended)

• Add remaining 9 path aliases to ZHTP node router
• Maintains backward compatibility
• No breaking changes to API client

Option B: Update API Client Paths

• Update the 9 remaining endpoints to use /api/v1 prefix
• Requires new API client version
• Breaking change for existing consumers

Option C: Hybrid Approach

• Add critical aliases (DAO, wallet) to node
• Update API client to use /api/v1 for new code
• Deprecate old paths post-alpha

Recommendation

Proceed with Option A to add the remaining 9 path aliases to the ZHTP node. This maintains full backward compatibility and unblocks the API client immediately.