Hedera Toolbox

Instructions

Implementation Reference

• src/modules/governance/tools.js:44-111 (handler)

  The handler logic for 'governance_monitor' which processes API requests, charges for the tool, fetches token/proposal info from Hedera Mirror Node, and calculates summaries.

  if (name === "governance_monitor") {
    const payment = chargeForTool("governance_monitor", 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 HCS messages if topic_id provided (look for governance messages)
    let proposals = [];
    if (args.topic_id) {
      const msgRes = await axios.get(
        `${base}/api/v1/topics/${args.topic_id}/messages?limit=100&order=desc`
      );
      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);
          if (parsed.type === "proposal" || parsed.proposal_id) {
            proposals.push({
              proposal_id: parsed.proposal_id || msg.sequence_number,
              title: parsed.title || "Untitled Proposal",
              status: parsed.status || "active",
              created_at: msg.consensus_timestamp,
              deadline: parsed.deadline || null,
              yes_votes: parsed.yes_votes || 0,
              no_votes: parsed.no_votes || 0,
              abstain_votes: parsed.abstain_votes || 0,
            });
          }
        } catch (e) {
          continue;
        }
      }
    }
  
    // Fetch recent token transactions as proxy for governance activity
    const txRes = await axios.get(
      `${base}/api/v1/tokens/${args.token_id}/nfts?limit=5`
    ).catch(() => ({ data: {} }));
  
    const holderRes = await axios.get(
      `${base}/api/v1/tokens/${args.token_id}/balances?limit=10&order=desc`
    ).catch(() => ({ data: { balances: [] } }));
  
    const topHolders = (holderRes.data.balances || []).slice(0, 5).map(b => ({
      account: b.account,
      balance: b.balance,
    }));
  
    return {
      token_id: args.token_id,
      token_name: token.name || "Unknown",
      token_symbol: token.symbol || "?",
      total_supply: token.total_supply,
      treasury: token.treasury_account_id,
      governance_topic: args.topic_id || null,
      active_proposals: proposals.filter(p => p.status !== "closed").length,
      proposals,
      top_holders: topHolders,
      summary: proposals.length === 0
        ? "No governance proposals found on this topic. The token may use off-chain voting or no topic_id was provided."
        : `Found ${proposals.length} proposal(s). Pass a proposal_id to governance_analyze for deep analysis.`,
      payment,
      timestamp: new Date().toISOString(),
    };
  }

• src/modules/governance/tools.js:11-24 (schema)

  The schema definition and metadata (name, description, input parameters) for the 'governance_monitor' tool.

  export const GOVERNANCE_TOOL_DEFINITIONS = [
    {
      name: "governance_monitor",
      description: "Monitor active governance proposals for a Hedera token or DAO. Returns open proposals, voting deadlines, and current vote tallies. Provide topic_id for best results — without it, only token metadata is returned. Costs 0.2 HBAR.",
      inputSchema: {
        type: "object",
        properties: {
          token_id: { type: "string", description: "Hedera token ID to monitor governance for (e.g. 0.0.123456)" },
          topic_id: { type: "string", description: "Optional HCS topic ID used for governance messages" },
          api_key: { type: "string", description: "Your HederaIntel API key" },
        },
        required: ["token_id", "api_key"],
      },
    },