[FRONTEND] [ALPHA]: API endpoint gaps between client and ZHTP node

[umwelt]

Overview

This is a tracking issue for API endpoint gaps between the API client library and the ZHTP node implementation that need to be resolved for the alpha release.

Status Update: Issues have been categorized into Node work vs Library work.

Issue Status Summary

Issue	Title	Type	Status
#3	Authentication endpoints	Node	✅ CLOSED - Already implemented
#4	Backup & Recovery	Node	🔴 OPEN - Needs node implementation
#5	Guardian Recovery	Node	🔴 OPEN - Needs node implementation
#6	Zero-Knowledge Proofs	Node	🔴 OPEN - Needs node implementation
#7	API path inconsistencies	Library	🔵 OPEN - Update paths to /api/v1
#8	Smart contract paths	Library	🔵 OPEN - Update to canonical paths
#9	Web4 resolution	Library	🔵 OPEN - Add new methods (blocked by node)
#10	Gas pricing	Library	🔵 OPEN - Update path (blocked by node)

Node Work Required

These issues require implementation on the ZHTP node:

🔴 Issue #4: Backup & Recovery System

• Node Issue: [Create in main repo]
• Missing Endpoints: 7 backup/recovery endpoints
• Priority: CRITICAL
• Blocks: Users cannot back up or recover identities

🔴 Issue #5: Guardian Social Recovery

• Node Issue: [Create in main repo]
• Missing Endpoints: 9 guardian management endpoints
• Priority: HIGH
• Blocks: Social recovery unavailable

🔴 Issue #6: Zero-Knowledge Proofs

• Node Issue: [Create in main repo]
• Missing Endpoints: ZKP generate/verify
• Priority: HIGH
• Blocks: Privacy features

Additional Node Issues Created:

• Node Issue #112: Missing 9 DAO/wallet/health endpoints
• Node Issue #113: Missing Web4/DHT resolution endpoints

Library Work Required

These issues require updates to the API client library:

🔵 Issue #7: Update API Paths

• Task: Update all old paths to use /api/v1 prefix
• Files: src/core/zhtp-api-methods.ts
• Lines: Multiple (14+ paths to update)
• Status: Node has aliases for backward compatibility (PR #109)

🔵 Issue #8: Update Contract Paths

• Task: Use canonical /api/v1/blockchain/contracts/* paths
• Files: src/core/zhtp-api-methods.ts
• Status: Node has aliases for backward compatibility (PR #109)

🔵 Issue #9: Add Web4 Methods

• Task: Add 3 new methods for DHT/Web4 resolution
• Files: src/core/zhtp-api-methods.ts
• Blocked by: Node Issue #113

🔵 Issue #10: Update Gas Path

• Task: Change /network/gas to /api/v1/network/gas
• Files: src/core/zhtp-api-methods.ts (line 579)
• Blocked by: Node Issue #112

Implementation Priority

Phase 1: CRITICAL (Blocks Alpha)

1. 🔴 Node: Implement backup/recovery endpoints (Issue [FRONTEND]: Backup and recovery system missing in ZHTP node #4)
2. 🔵 Library: Update all paths to /api/v1 (Issues [FRONTEND]: API path inconsistencies between client and node #7, [FRONTEND]: Smart contract endpoints incomplete in ZHTP node #8, [FRONTEND]: Network gas pricing endpoint missing #10)
3. ✅ DONE: Authentication working (Issue [FRONTEND]: Authentication endpoints missing in ZHTP node #3)
4. ✅ DONE: Node path aliases added (PR #109)

Phase 2: HIGH (Important for Alpha)

5. 🔴 Node: Implement guardian recovery (Issue [FRONTEND]: Guardian recovery system missing in ZHTP node #5)
6. 🔴 Node: Implement ZK proof endpoints (Issue [FRONTEND]: Zero-knowledge proof endpoints missing in ZHTP node #6)
7. 🔴 Node: Implement missing DAO/wallet endpoints (Issue #112)

Phase 3: MEDIUM (Nice to Have)

8. 🔴 Node: Implement Web4/DHT resolution (Issue #113)
9. 🔵 Library: Add Web4 resolution methods (Issue [FRONTEND]: Web4 domain resolution endpoints need alignment #9)

Alpha Release Readiness

Can Ship Alpha Without:

• Guardian recovery (Issue [FRONTEND]: Guardian recovery system missing in ZHTP node #5) - users can use seed phrases
• ZK proofs (Issue [FRONTEND]: Zero-knowledge proof endpoints missing in ZHTP node #6) - privacy features deferred
• DHT resolution (Issue #113) - Web4Manager resolution works

Must Have for Alpha:

• ✅ Authentication (Issue [FRONTEND]: Authentication endpoints missing in ZHTP node #3)
• 🔴 Backup/recovery (Issue [FRONTEND]: Backup and recovery system missing in ZHTP node #4)
• 🔵 All library paths updated (Issues [FRONTEND]: API path inconsistencies between client and node #7, [FRONTEND]: Smart contract endpoints incomplete in ZHTP node #8, [FRONTEND]: Network gas pricing endpoint missing #10)
• 🔴 Core DAO/wallet endpoints (Issue #112)

Related Work

ZHTP Node Issues:

• Issue #111: Test compilation errors (lib-proofs, lib-economy)
• Issue #112: Missing DAO/wallet/health endpoints
• Issue #113: Missing Web4/DHT resolution endpoints
• PR #109: Path aliases for backward compatibility ✅

API Client Library:

• All library issues ([FRONTEND]: API path inconsistencies between client and node #7, [FRONTEND]: Smart contract endpoints incomplete in ZHTP node #8, [FRONTEND]: Web4 domain resolution endpoints need alignment #9, [FRONTEND]: Network gas pricing endpoint missing #10) converted to implementation tasks
• Ready for updates once node endpoints are implemented

Next Actions

1. Create node issues for [FRONTEND]: Backup and recovery system missing in ZHTP node #4, [FRONTEND]: Guardian recovery system missing in ZHTP node #5, [FRONTEND]: Zero-knowledge proof endpoints missing in ZHTP node #6 (backup, guardian, ZKP)
2. Update library paths in Issues [FRONTEND]: API path inconsistencies between client and node #7, [FRONTEND]: Smart contract endpoints incomplete in ZHTP node #8, [FRONTEND]: Network gas pricing endpoint missing #10
3. Wait for node Issue #112 to complete
4. Add library methods in Issue [FRONTEND]: Web4 domain resolution endpoints need alignment #9 once node Issue #113 completes

[umwelt]

✅ Node-Side Issues Created

I've verified the endpoint gaps and created tracking issues on The-Sovereign-Network repo for the missing critical endpoints:

Critical Blockers (P0)

• #99 - [ALPHA-FE-1] Implement signin/login API endpoints for authentication

  • POST /api/v1/identity/signin
  • POST /api/v1/identity/login
  • Status: These endpoints do NOT exist on the node
  • Impact: Users cannot sign into existing accounts - complete blocker

• #100 - [ALPHA-FE-2] Implement backup/recovery API endpoints

  • 4 backup/recovery endpoints needed
  • Status: Zero backup/recovery endpoints exist (though RecoveryPhraseManager exists in lib-identity)
  • Impact: Users cannot back up or recover accounts

High Priority (P1)

• #101 - [ALPHA-FE-3] Implement guardian social recovery system

  • 9 guardian management and recovery endpoints
  • Status: No guardian system implemented
  • Impact: Social recovery unavailable (nice-to-have for alpha)

• #102 - [ALPHA-FE-4] Implement zero-knowledge proof API endpoints

  • POST /api/v1/zkp/generate
  • POST /api/v1/zkp/verify
  • Status: lib-proofs exists but no HTTP endpoints
  • Impact: Privacy features unavailable

Analysis Summary

Verified: The ZHTP node currently has these handlers registered:

/api/v1/blockchain  ✅
/api/v1/identity    ⚠️ (partial - only create/get/citizenship/sign)
/api/v1/storage     ✅
/api/v1/wallet      ✅
/api/v1/dao         ✅
/api/v1/dht         ✅
/api/v1/dns         ✅
/api/v1/web4        ✅
/api/v1/validator   ✅
/api/v1/protocol    ✅

Missing from /api/v1/identity:

• signin/login endpoints
• backup/recovery endpoints
• guardian management
• No session management integration

Impact on Frontend:
The mobile/desktop apps literally cannot function without #99 and #100. These are hard blockers for any frontend development or alpha release with frontends.

Recommendation

For Alpha Release:

1. MUST HAVE: Issues #99, #100 (signin/login, backup/recovery)
2. SHOULD HAVE: Issue #102 (ZKP endpoints) - can start with just age_over_18 proof
3. NICE TO HAVE: Issue #101 (guardian system) - can defer to post-alpha

Estimated Effort:

• #99 (signin/login): 2-3 days
• #100 (backup/recovery): 3-4 days
• #102 (ZKP basic): 2-3 days
• #101 (guardians): 5-7 days (complex feature)

Total for MVP: ~7-10 days for critical path (#99, #100, #102 basic)

[umwelt]

Status Update - Library Work Complete

All library-side issues have been implemented and PRs created:

Issue	Title	PR	Status
#7	API path inconsistencies	#13	✅ PR Created
#8	Smart contract paths	#14	✅ PR Created
#9	Web4 resolution methods	#15	✅ PR Created
#10	Gas pricing type safety	#16	✅ PR Created

Changes Summary

PR #13 - Fix API Path Inconsistencies (Issue #7)

• Updated 17 endpoint paths to use /api/v1 prefix
• DAO, blockchain, network, protocol, and wallet endpoints
• All paths now align with ZHTP node implementation

PR #14 - Update Smart Contract Endpoints (Issue #8)

• Deploy: /api/v1/contract/deploy → /api/v1/blockchain/contracts/deploy
• Execute: /api/v1/contract/execute → /api/v1/blockchain/contracts/{id}/call
• Query: POST /api/v1/contract/query/{id} → GET /api/v1/blockchain/contracts/{id}/state
• Moved contractId from body to URL path
• Changed query from POST to GET

PR #15 - Add Web4/DHT Resolution Methods (Issue #9)

• Added resolveWeb4ViaDht(domain) method
• Added getContractFromDht(contractId) method
• Improved getContractByHash(hash) with JSDoc and proper types
• Ready for use once node implements endpoints (blocked by node Issue #113)

PR #16 - Improve Gas Info Type Safety (Issue #10)

• Changed return type from Promise<any> to Promise<GasInfo>
• Better TypeScript type checking for gas pricing data

Node Dependencies

Library changes are complete, but some methods require node endpoint implementation:

• Issue [FRONTEND]: Web4 domain resolution endpoints need alignment #9 (Web4/DHT): Blocked by node Issue #113
• Issue [FRONTEND]: Network gas pricing endpoint missing #10 (Gas): Blocked by node Issue #112

All other endpoints work with existing node implementation via path aliases (ZHTP node PR #109).

Next Steps

1. Review and merge PRs Fix API path inconsistencies - use /api/v1 prefix #13, Update smart contract endpoints to canonical paths #14, Add Web4/DHT domain resolution methods #15, Improve getGasInfo() type safety #16
2. Wait for node Issue #112 (DAO/wallet/gas endpoints)
3. Wait for node Issue #113 (Web4/DHT endpoints)
4. Test all endpoints against live ZHTP node