[IMPLEMENTATION GUIDE] Complete ZHTP Node API Endpoint Reference

[umwelt]

Overview

This issue provides a comprehensive reference of all API endpoints currently available on the ZHTP node. Use this as a guide to implement missing methods in the API client library.

Status Summary

The ZHTP node now has 90+ endpoints implemented across all major categories. The API client needs to be updated to include methods for all these endpoints.

Endpoint Categories

1. Authentication & Identity Management (15 endpoints)

Authentication

• ✅ POST /api/v1/identity/create - Create new identity
• ✅ POST /api/v1/identity/signin - Sign in with DID + passphrase
• ✅ POST /api/v1/identity/login - Login (alias for signin)
• ✅ GET /api/v1/identity/{id} - Get identity details

Backup & Recovery (Issue #4 - CLOSED)

• ✅ POST /api/v1/identity/backup/generate - Generate recovery phrase
• ✅ POST /api/v1/identity/backup/verify - Verify recovery phrase
• ✅ POST /api/v1/identity/recover - Recover identity from phrase
• ✅ GET /api/v1/identity/backup/status - Check backup status
• ✅ POST /api/v1/identity/backup/export - Export encrypted backup
• ✅ POST /api/v1/identity/backup/import - Import encrypted backup
• ✅ POST /api/v1/identity/seed/verify - Verify seed phrase (12-word BIP39)

Other Identity

• ✅ POST /api/v1/identity/citizenship/apply - Apply for citizenship
• ✅ POST /api/v1/identity/sign - Sign message with identity
• ✅ POST /api/v1/identity/password/recover - Password recovery

2. Guardian Social Recovery (9 endpoints) - Issue #5 CLOSED

• ✅ POST /api/v1/identity/guardians/add - Add guardian
• ✅ DELETE /api/v1/identity/guardians/{guardian_id} - Remove guardian
• ✅ GET /api/v1/identity/guardians - List guardians
• ✅ POST /api/v1/identity/recovery/initiate - Initiate recovery
• ✅ POST /api/v1/identity/recovery/{recovery_id}/approve - Guardian approves
• ✅ POST /api/v1/identity/recovery/{recovery_id}/complete - Complete recovery
• ✅ POST /api/v1/identity/recovery/{recovery_id}/reject - Guardian rejects
• ✅ GET /api/v1/identity/recovery/{recovery_id}/status - Check status
• ✅ GET /api/v1/identity/recovery/pending - List pending requests

3. Zero-Knowledge Proofs (2 endpoints) - Issue #6 CLOSED

• ✅ POST /api/v1/zkp/generate - Generate ZK proof
  • Proof types: age_over_18, age_range, citizenship_verified, jurisdiction_membership
• ✅ POST /api/v1/zkp/verify - Verify ZK proof

4. DAO Operations (13 endpoints) - Part of Issue #112 CLOSED

Treasury

• ✅ GET /api/v1/dao/treasury/status - Get treasury status
• ✅ GET /api/v1/dao/treasury/transactions - List transactions (with pagination)

Proposals

• ✅ POST /api/v1/dao/proposal/create - Create proposal
• ✅ GET /api/v1/dao/proposals/list - List proposals (with filters)
• ✅ GET /api/v1/dao/proposal/{proposal_id} - Get proposal details
• ✅ POST /api/v1/dao/proposals/spending - Create spending proposal

Voting

• ✅ POST /api/v1/dao/vote/cast - Cast vote
• ✅ GET /api/v1/dao/vote/power/{identity_id} - Get voting power
• ✅ GET /api/v1/dao/votes/{proposal_id} - Get proposal votes

Delegates

• ✅ GET /api/v1/dao/data - Get DAO data
• ✅ GET /api/v1/dao/delegates - List delegates
• ✅ POST /api/v1/dao/delegates/register - Register as delegate
• ✅ POST /api/v1/dao/delegates/revoke - Revoke delegate

5. Wallet Operations (8 endpoints) - Part of Issue #112 CLOSED

• ✅ GET /api/v1/wallet/balance/{type}/{id} - Get wallet balance
• ✅ GET /api/v1/wallet/list/{identity_id} - List wallets for identity
• ✅ POST /api/v1/wallet/send - Send transaction
• ✅ GET /api/v1/wallet/transactions/{id} - Get wallet transactions
• ✅ GET /api/v1/wallet/statistics/{id} - Get wallet statistics
• ✅ POST /api/v1/wallet/staking/stake - Stake tokens
• ✅ POST /api/v1/wallet/staking/unstake - Unstake tokens
• ✅ POST /api/v1/wallet/transfer/cross-wallet - Transfer between wallets

6. Blockchain Operations (22 endpoints)

Blocks & Transactions

• ✅ GET /api/v1/blockchain/status - Get blockchain status
• ✅ GET /api/v1/blockchain/latest - Get latest block
• ✅ GET /api/v1/blockchain/tip - Get blockchain tip
• ✅ GET /api/v1/blockchain/blocks/{height} - Get block by height
• ✅ GET /api/v1/blockchain/block/{hash} - Get block by hash
• ✅ POST /api/v1/blockchain/transaction/broadcast - Broadcast transaction
• ✅ GET /api/v1/blockchain/transaction/{hash} - Get transaction
• ✅ POST /api/v1/blockchain/transaction/estimate-fee - Estimate fee
• ✅ GET /api/v1/blockchain/transactions/pending - Get pending transactions
• ✅ GET /api/v1/blockchain/mempool - Get mempool status
• ✅ GET /api/v1/blockchain/balance/{address} - Get address balance

Smart Contracts

• ✅ POST /api/v1/blockchain/contracts/deploy - Deploy contract
• ✅ GET /api/v1/blockchain/contracts - List contracts
• ✅ GET /api/v1/blockchain/contracts/{address} - Get contract details

Network & Peers

• ✅ GET /api/v1/blockchain/network/peers - List network peers
• ✅ GET /api/v1/blockchain/network/stats - Get network statistics
• ✅ POST /api/v1/blockchain/network/peer/add - Add peer
• ✅ GET /api/v1/blockchain/network/peer/{peer_id} - Get peer info

Sync & Performance

• ✅ GET /api/v1/blockchain/sync/metrics - Get sync metrics
• ✅ GET /api/v1/blockchain/sync/peers - Get sync peers
• ✅ GET /api/v1/blockchain/sync/performance - Get sync performance
• ✅ GET /api/v1/blockchain/edge-stats - Get edge statistics

7. Network & Protocol (6 endpoints) - Part of Issue #112 CLOSED

Network

• ✅ GET /api/v1/network/gas - Get gas pricing (Issue [FRONTEND]: Network gas pricing endpoint missing #10 - CLOSED)

Protocol Info

• ✅ GET /api/v1/protocol/info - Get protocol information
• ✅ GET /api/v1/protocol/version - Get protocol version
• ✅ GET /api/v1/protocol/health - Health check
• ✅ GET /api/v1/protocol/capabilities - Get capabilities
• ✅ GET /api/v1/protocol/stats - Get protocol statistics

8. Storage Operations (7 endpoints)

• ✅ POST /api/v1/storage/put - Store data
• ✅ POST /api/v1/storage/store - Store data (alias)
• ✅ GET /api/v1/storage/get - Retrieve data
• ✅ DELETE /api/v1/storage/delete - Delete data
• ✅ GET /api/v1/storage/status - Get storage status
• ✅ GET /api/v1/storage/stats - Get storage statistics

9. Web4 & Content (3+ endpoints) - Issue #113 REMAINING

• ✅ GET /api/v1/web4/domains/{domain} - Resolve domain
• ✅ GET /api/v1/web4/content/{cid} - Get content by CID
• ✅ POST /api/v1/web4/load - Load Web4 resource

10. Validator Operations (3 endpoints)

• ✅ POST /api/v1/validator/register - Register validator
• ✅ GET /api/v1/validator/{validator_id} - Get validator info
• ✅ GET /api/v1/validators - List validators

11. Cryptography Operations (3 endpoints)

• ✅ POST /api/v1/crypto/generate_keypair - Generate keypair
• ✅ POST /api/v1/crypto/sign_message - Sign message
• ✅ POST /api/v1/crypto/verify_signature - Verify signature

12. Mesh Operations

• ✅ POST /api/v1/mesh/create - Create mesh network

Backward Compatibility Aliases (Issue #7, #8 - CLOSED)

The node supports both old and new paths via backward compatibility aliases:

Old Path → New Path Mappings

• /dao/proposals → /api/v1/dao/proposals/list
• /dao/vote → /api/v1/dao/vote/cast
• /dao/treasury → /api/v1/dao/treasury/status
• /mesh/peers → /api/v1/blockchain/network/peers
• /node/status → /api/v1/protocol/info
• /blockchain/info → /api/v1/blockchain/status
• /network/gas → /api/v1/network/gas
• /wallet/balance → /api/v1/wallet/balance/{type}/{id}
• /wallet/transactions → /api/v1/wallet/transactions/{id}
• /api/v1/contract/* → /api/v1/blockchain/contracts/*

Implementation Tasks for API Client

Priority 1: Update Existing Methods (Issues #7, #8, #10)

• Update all paths to use /api/v1 prefix
• Update contract paths to /api/v1/blockchain/contracts
• Update gas pricing path
• Test backward compatibility with old paths

Priority 2: Add Missing Identity Methods (Issues #4, #5)

• Add backup/recovery methods (7 endpoints)
• Add guardian management methods (9 endpoints)
• Add seed verification method

Priority 3: Add ZK Proof Methods (Issue #6)

• Add generateZkProof() method
• Add verifyZkProof() method
• Add proof type enums

Priority 4: Add DAO Methods (Part of Issue #112)

• Add treasury methods (2 endpoints)
• Add proposal methods (4 endpoints)
• Add voting methods (3 endpoints)
• Add delegate methods (4 endpoints)

Priority 5: Add Wallet Methods (Part of Issue #112)

• Add staking methods (2 endpoints)
• Add cross-wallet transfer
• Add wallet statistics

Priority 6: Add Network & Protocol Methods

• Add gas pricing method
• Add protocol info methods (5 endpoints)

Priority 7: Add Web4 Methods (Issue #9)

• Add domain resolution
• Add content retrieval
• Add resource loading

Request/Response Type Definitions Needed

Authentication

interface SigninRequest {
  did: string;
  passphrase: string;
}

interface LoginRequest {
  identity_id: string;
  passphrase: string;
}

Backup/Recovery

interface GenerateRecoveryPhraseRequest {
  identity_id: string;
  session_token: string;
}

interface ExportBackupRequest {
  identity_id: string;
  passphrase: string; // Min 12 chars
}

interface ImportBackupRequest {
  backup_data: string; // Base64
  passphrase: string;
}

Guardian Recovery

interface AddGuardianRequest {
  identity_id: string;
  guardian_did: string;
  guardian_name: string;
}

interface InitiateRecoveryRequest {
  identity_did: string;
  requester_device: string;
}

ZK Proofs

interface GenerateProofRequest {
  identity_id: string;
  proof_type: 'age_over_18' | 'age_range' | 'citizenship_verified' | 'jurisdiction_membership';
  credential_data: {
    age?: number;
    jurisdiction?: string;
    is_verified_citizen?: boolean;
  };
}

interface VerifyProofRequest {
  proof: {
    proof_data: string;
    public_inputs: string[];
    proof_type: string;
    generated_at: number;
    valid_until: number;
  };
}

DAO Operations

interface CreateProposalRequest {
  proposer_id: string;
  title: string;
  description: string;
  proposal_type: string;
  voting_period_days: number;
}

interface CastVoteRequest {
  proposal_id: string;
  voter_id: string;
  vote: 'yes' | 'no' | 'abstain';
  voting_power?: number;
}

Security Notes

All authenticated endpoints require:

• Authorization: Bearer <session_token> header
• IP and User-Agent binding for session validation

Rate limits:

• Authentication: 10 attempts/15 min per IP
• Backup export: 5/hour per IP
• Backup import: 3/hour per IP
• Recovery: 3/hour per IP
• ZK proof generation: 10/hour per IP
• ZK proof verification: 100/15 min

Related Issues

Closed Node Issues:

• #84 - Authentication endpoints ✅
• #85 - Backup/recovery system ✅
• #86 - Path aliases ✅
• #87 - Guardian recovery ✅
• #88 - ZK proofs ✅
• #89 - Gas pricing ✅
• #112 - Missing endpoints meta ✅
• #115 - Backup/recovery endpoints ✅
• #116 - Guardian endpoints ✅
• #117 - ZK proof endpoints ✅
• #118 - DAO/wallet/network endpoints ✅

Open Node Issues:

• #113 - Web4/DHT resolution (3 endpoints remaining)
• #131 - ZK proof production upgrade (Bulletproofs/Plonky2)

API Client Issues:

• [FRONTEND]: Authentication endpoints missing in ZHTP node #3 - Authentication ✅
• [FRONTEND]: Backup and recovery system missing in ZHTP node #4 - Backup/recovery (node complete, client needs update)
• [FRONTEND]: Guardian recovery system missing in ZHTP node #5 - Guardian recovery (node complete, client needs update)
• [FRONTEND]: Zero-knowledge proof endpoints missing in ZHTP node #6 - ZK proofs (node complete, client needs update)
• [FRONTEND]: API path inconsistencies between client and node #7 - Path updates (node has aliases, client should update)
• [FRONTEND]: Smart contract endpoints incomplete in ZHTP node #8 - Contract paths (node has aliases, client should update)
• [FRONTEND]: Web4 domain resolution endpoints need alignment #9 - Web4 methods (blocked by node #113)
• [FRONTEND]: Network gas pricing endpoint missing #10 - Gas pricing (node complete, client needs update)
• [FRONTEND] [ALPHA]: API endpoint gaps between client and ZHTP node #11 - Tracking issue

Total Endpoint Count

Implemented: 90+ endpoints

• Authentication & Identity: 15
• Guardian Recovery: 9
• Zero-Knowledge Proofs: 2
• DAO Operations: 13
• Wallet Operations: 8
• Blockchain: 22
• Network & Protocol: 6
• Storage: 7
• Web4 & Content: 3
• Validators: 3
• Cryptography: 3
• Mesh: 1

Remaining: 3 endpoints (Web4/DHT in issue #113)

Next Steps

1. Start with Priority 1 (path updates) - node has backward compatibility
2. Add missing method implementations for P2-P7
3. Add TypeScript type definitions for all request/response types
4. Update documentation
5. Add integration tests
6. Wait for node issue #113 completion before implementing Web4 methods

This represents 90% completion on the node side. The API client implementation can proceed immediately!

[umwelt]

🎯 Implementation Plan - Sub-Issues Created

This comprehensive guide has been broken down into 8 smaller, actionable issues for efficient implementation:

Priority 1: Path Updates ✅

Issue: #18 - [P1] Verify and update API paths to /api/v1 standard
Effort: Small (2-3 hours)
Focus: Ensure all methods use /api/v1 paths, test backward compatibility

Priority 2: Backup & Recovery 🔐

Issue: #19 - [P2] Implement Backup & Recovery API methods (7 endpoints)
Effort: Medium (4-6 hours)
Missing: getBackupStatus()

Priority 3: Guardian Social Recovery 👥

Issue: #20 - [P3] Implement Guardian Social Recovery methods (9 endpoints)
Effort: Medium-Large (6-8 hours)
Missing: completeRecovery(), rejectRecovery(), getPendingRecoveries()

Priority 4: Zero-Knowledge Proofs 🔏

Issue: #21 - [P4] Implement Zero-Knowledge Proof methods (2 endpoints)
Effort: Small-Medium (3-4 hours)
Missing: Both generateZkProof() and verifyZkProof()
Note: Currently uses simulated proofs (see node issue #131)

Priority 5: DAO Operations 🏛️

Issue: #22 - [P5] Implement DAO API methods (13 endpoints)
Effort: Large (8-10 hours)
Categories: Treasury (2), Proposals (4), Voting (3), Delegates (4)

Priority 6: Wallet Operations 💰

Issue: #23 - [P6] Implement Wallet API methods (8 endpoints)
Effort: Medium-Large (6-8 hours)
Categories: Balances (2), Transactions (4), Addresses (2)

Priority 7: Network & Protocol 🌐

Issue: #24 - [P7] Implement Network & Protocol API methods (6 endpoints)
Effort: Small-Medium (3-5 hours)
Categories: Network status (3), Protocol info (2), Gas pricing (1)

Priority 8: Web4 Domains 🌍

Issue: #25 - [P8] Implement Web4 Domain & Content API methods (3 endpoints)
Effort: Small (2-3 hours)
Categories: Domain registration, resolution, content retrieval

---

📊 Summary

• Total Sub-Issues: 8
• Total Endpoints: 48 (from the priority categories)
• Estimated Total Effort: 33-49 hours
• Recommended Order: P1 → P2 → P3 → P4 → P5 → P6 → P7 → P8

🚀 Getting Started

1. Start with Issue [P1] Verify and update API paths to /api/v1 standard #18 (Path Updates) - this is foundational
2. Continue with P2-P4 (Security features) - critical for alpha
3. Implement P5-P6 (DAO & Wallet) - core platform features
4. Finish with P7-P8 (Network & Web4) - nice-to-have features

Each issue contains:

• Detailed endpoint specifications
• Request/response types
• Implementation checklist
• Testing guidelines
• Documentation requirements
• Usage examples

This issue (#17) will remain open as the master tracking issue. Close sub-issues as they're completed.