Overview

Implement all DAO (Decentralized Autonomous Organization) API methods in the TypeScript client to match the ZHTP node's DAO endpoints.

Related to: #17 - Comprehensive API Implementation Guide
Priority: P5 - HIGH (Core governance feature)
Estimated Effort: Large (8-10 hours)

Background

The ZHTP node has 13 DAO endpoints across 4 categories:

• Treasury management (2 endpoints)
• Proposal management (4 endpoints)
• Voting system (3 endpoints)
• Delegate system (4 endpoints)

The API client already has some DAO methods implemented, but needs verification and possible additions.

Required Methods

Treasury Methods (2 endpoints)

1. getDaoTreasuryBalance() ✅ EXISTS - NEEDS VERIFICATION

Endpoint: GET /api/v1/dao/treasury/balance

Expected Response:

{
  status: "success",
  balance: 1000000,
  currency: "SOVEREIGN",
  pending_disbursements: 50000
}

Action: Verify implementation matches node response format

2. getDaoTreasuryTransactions() ❌ MISSING

Endpoint: GET /api/v1/dao/treasury/transactions

Expected Response:

{
  status: "success",
  transactions: [
    {
      tx_id: "...",
      type: "disbursement" | "deposit",
      amount: 1000,
      timestamp: 1234567890,
      proposal_id: "..."
    }
  ]
}

Action: Implement new method

Proposal Methods (4 endpoints)

3. createDaoProposal() ✅ EXISTS - NEEDS VERIFICATION

Endpoint: POST /api/v1/dao/proposals/create

Request:

{
  title: string,
  description: string,
  proposal_type: "funding" | "governance" | "technical",
  funding_amount?: number,
  voting_period_days: number
}

Action: Verify implementation and add missing fields if needed

4. getDaoProposals() ✅ EXISTS - NEEDS VERIFICATION

Endpoint: GET /api/v1/dao/proposals/list

Query params: ?status=active&limit=10&offset=0

Action: Verify query parameter support

5. getDaoProposal() ✅ EXISTS - NEEDS VERIFICATION

Endpoint: GET /api/v1/dao/proposals/{proposal_id}

Action: Verify implementation

6. executeDaoProposal() ❌ MISSING

Endpoint: POST /api/v1/dao/proposals/{proposal_id}/execute

Expected Response:

{
  status: "success",
  executed: true,
  execution_tx: "..."
}

Action: Implement new method

Voting Methods (3 endpoints)

7. castDaoVote() ✅ EXISTS - NEEDS VERIFICATION

Endpoint: POST /api/v1/dao/vote/cast

Request:

{
  proposal_id: string,
  vote: "yes" | "no" | "abstain",
  voting_power?: number
}

Action: Verify implementation

8. getDaoVoteStatus() ❌ MISSING

Endpoint: GET /api/v1/dao/vote/status/{proposal_id}

Expected Response:

{
  status: "success",
  proposal_id: "...",
  votes_yes: 1000,
  votes_no: 500,
  votes_abstain: 100,
  total_voting_power: 1600,
  current_result: "passing" | "failing"
}

Action: Implement new method

9. getUserDaoVote() ❌ MISSING

Endpoint: GET /api/v1/dao/vote/user/{proposal_id}

Expected Response:

{
  status: "success",
  has_voted: true,
  vote: "yes" | "no" | "abstain",
  voting_power: 100,
  timestamp: 1234567890
}

Action: Implement new method

Delegate Methods (4 endpoints)

10. delegateDaoVotingPower() ❌ MISSING

Endpoint: POST /api/v1/dao/delegate/assign

Request:

{
  delegate_to: string, // DID of delegate
  voting_power?: number // Optional partial delegation
}

Expected Response:

{
  status: "success",
  delegated_to: "did:zhtp:...",
  voting_power: 100
}

Action: Implement new method

11. revokeDaoDelegation() ❌ MISSING

Endpoint: POST /api/v1/dao/delegate/revoke

Expected Response:

{
  status: "success",
  revoked: true
}

Action: Implement new method

12. getDaoDelegations() ❌ MISSING

Endpoint: GET /api/v1/dao/delegate/list

Expected Response:

{
  status: "success",
  delegations: [
    {
      delegate: "did:zhtp:...",
      voting_power: 100,
      delegated_at: 1234567890
    }
  ],
  total_delegated: 100,
  available_power: 50
}

Action: Implement new method

13. getDaoDelegate() ❌ MISSING

Endpoint: GET /api/v1/dao/delegate/{delegate_did}

Expected Response:

{
  status: "success",
  delegate_did: "did:zhtp:...",
  total_power_received: 500,
  active_delegators: 10,
  voting_history: [...]
}

Action: Implement new method

Implementation Checklist

Phase 1: Verify Existing Methods

• Verify getDaoTreasuryBalance() response format
• Verify createDaoProposal() supports all proposal types
• Verify getDaoProposals() supports query parameters (status, limit, offset)
• Verify getDaoProposal() implementation
• Verify castDaoVote() supports all vote types

Phase 2: Implement Missing Methods

• Implement getDaoTreasuryTransactions()
• Implement executeDaoProposal()
• Implement getDaoVoteStatus()
• Implement getUserDaoVote()
• Implement delegateDaoVotingPower()
• Implement revokeDaoDelegation()
• Implement getDaoDelegations()
• Implement getDaoDelegate()

Phase 3: Testing

• Test treasury methods with mock data
• Test proposal creation and retrieval
• Test voting flow (create proposal → cast vote → check status)
• Test delegation flow (delegate → check → revoke)
• Test error handling for all methods

Phase 4: Documentation

• Add JSDoc comments to all methods
• Document proposal types and voting options
• Create usage examples for each category
• Update main README with DAO examples

Files to Modify

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

Success Criteria

• All 13 DAO endpoints have corresponding TypeScript methods
• All methods use /api/v1 paths
• Response types match node implementation
• All methods handle errors properly
• Full test coverage for DAO functionality
• Documentation complete

Priority Rationale

DAO functionality is critical for decentralized governance. Users need to be able to:

• Participate in governance through proposals and voting
• Manage treasury funds transparently
• Delegate voting power for liquid democracy

This is a core feature for any Web3 platform and should be implemented early in the API client development cycle.

Dependencies

• Session authentication (already implemented)
• Identity management (already implemented)
• 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)