Hedera Toolbox

Instructions

Implementation Reference

• src/modules/governance/tools.js:114-218 (handler)

  Handler implementation for the governance_analyze tool, which performs deep analysis of a proposal.

  if (name === "governance_analyze") {
    const payment = chargeForTool("governance_analyze", args.api_key);
    const base = getMirrorNodeBase();
  
    // Fetch token info
    const tokenRes = await axios.get(`${base}/api/v1/tokens/${args.token_id}`);
    const token = tokenRes.data;
  
    // Fetch all votes for this proposal from HCS topic if provided
    let votes = { yes: 0, no: 0, abstain: 0, total: 0, voters: [] };
    let proposalDetails = null;
  
    if (args.topic_id) {
      const msgRes = await axios.get(
        `${base}/api/v1/topics/${args.topic_id}/messages?limit=100&order=asc`
      );
      const messages = msgRes.data.messages || [];
  
      for (const msg of messages) {
        try {
          const content = Buffer.from(msg.message, "base64").toString("utf-8");
          const parsed = JSON.parse(content);
  
          // Find the original proposal
          if (
            (parsed.type === "proposal" || parsed.proposal_id) &&
            String(parsed.proposal_id || msg.sequence_number) === String(args.proposal_id)
          ) {
            proposalDetails = {
              title: parsed.title || "Untitled Proposal",
              description: parsed.description || "No description provided.",
              created_at: msg.consensus_timestamp,
              deadline: parsed.deadline || null,
              proposer: parsed.proposer || null,
            };
          }
  
          // Tally votes for this proposal
          if (parsed.type === "vote" && String(parsed.proposal_id) === String(args.proposal_id)) {
            const v = (parsed.vote || "").toLowerCase();
            if (v === "yes") votes.yes++;
            else if (v === "no") votes.no++;
            else votes.abstain++;
            votes.total++;
            votes.voters.push({ voter: parsed.voter_id, vote: v, timestamp: msg.consensus_timestamp });
          }
        } catch (e) {
          continue;
        }
      }
    }
  
    // Token holder concentration
    const holderRes = await axios.get(
      `${base}/api/v1/tokens/${args.token_id}/balances?limit=20&order=desc`
    ).catch(() => ({ data: { balances: [] } }));
  
    const holders = holderRes.data.balances || [];
    const totalSupply = parseInt(token.total_supply || 0);
    const top5Balance = holders.slice(0, 5).reduce((s, b) => s + parseInt(b.balance || 0), 0);
    const concentrationPct = totalSupply > 0 ? ((top5Balance / totalSupply) * 100).toFixed(1) : "unknown";
  
    // Participation rate
    const participationRate = votes.total > 0 && holders.length > 0
      ? ((votes.total / holders.length) * 100).toFixed(1) + "%"
      : "unknown";
  
    // Simple outcome prediction
    let prediction = "Insufficient votes to predict outcome.";
    if (votes.total > 0) {
      const yesPct = (votes.yes / votes.total) * 100;
      const noPct = (votes.no / votes.total) * 100;
      if (yesPct > 60) prediction = "Likely to PASS - strong yes majority.";
      else if (noPct > 60) prediction = "Likely to FAIL - strong no majority.";
      else if (yesPct > noPct) prediction = "Leaning YES but outcome uncertain.";
      else if (noPct > yesPct) prediction = "Leaning NO but outcome uncertain.";
      else prediction = "Tied - outcome is uncertain.";
    }
  
    return {
      proposal_id: args.proposal_id,
      token_id: args.token_id,
      token_name: token.name || "Unknown",
      proposal: proposalDetails || { note: "Proposal details not found in topic. It may use off-chain governance." },
      vote_tally: {
        yes: votes.yes,
        no: votes.no,
        abstain: votes.abstain,
        total: votes.total,
        yes_pct: votes.total > 0 ? ((votes.yes / votes.total) * 100).toFixed(1) + "%" : "0%",
        no_pct: votes.total > 0 ? ((votes.no / votes.total) * 100).toFixed(1) + "%" : "0%",
      },
      participation_rate: participationRate,
      token_concentration: {
        top_5_holders_pct: concentrationPct + "%",
        note: concentrationPct > 50
          ? "High concentration - top 5 holders control majority of supply."
          : "Reasonably distributed token supply.",
      },
      outcome_prediction: prediction,
      recent_voters: votes.voters.slice(-10),
      payment,
      timestamp: new Date().toISOString(),
    };
  }

• src/modules/governance/tools.js:26-38 (schema)

  Input schema and tool definition for governance_analyze.

    name: "governance_analyze",
    description: "Deep analysis of a governance proposal including voter sentiment, participation rate, token concentration, and outcome prediction. Costs 1.0 HBAR.",
    inputSchema: {
      type: "object",
      properties: {
        token_id: { type: "string", description: "Hedera token ID the proposal belongs to" },
        proposal_id: { type: "string", description: "Proposal ID or HCS sequence number to analyze" },
        topic_id: { type: "string", description: "HCS topic ID where proposal votes are recorded" },
        api_key: { type: "string", description: "Your HederaIntel API key" },
      },
      required: ["token_id", "proposal_id", "api_key"],
    },
  },

• src/tools.js:247-247 (registration)

  Tool registration for governance_analyze within the main tools registry.

  name: "governance_analyze",