@akta/dao-cli 0.1.0

package/README.md

@@ -0,0 +1,137 @@
+# Akita DAO CLI
+
+A read-only CLI and interactive TUI for exploring [Akita DAO](https://akita.community) on-chain state on Algorand. Query DAO configuration, fees, proposals, wallet plugins, and more — all from your terminal.
+
+<p align="center">
+  <img src="images/dao_view_styled.png" alt="DAO overview" width="800" />
+</p>
+
+## Install
+
+**One-liner** (installs [Bun](https://bun.sh) if needed):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/akita-protocol/dao-cli/main/install.sh | bash
+```
+
+**Or with npm / bun:**
+
+```bash
+npx @akta/dao-cli
+bun add -g @akta/dao-cli
+```
+
+## Interactive TUI
+
+Running `akita-dao` with no arguments launches a full-screen interactive dashboard. Navigate with keyboard shortcuts to explore every aspect of the DAO.
+
+| Key | Action |
+|-----|--------|
+| `Tab` / `Shift+Tab` | Switch tabs |
+| `[` `]` | Cycle items (proposals, accounts) |
+| `↑` `↓` `k` `j` | Scroll |
+| `PgUp` `PgDn` | Scroll fast |
+| `g` / `G` | Jump to top / bottom |
+| `r` | Refresh data |
+| `q` | Quit |
+
+### DAO Tab
+
+Full DAO overview — core settings, asset supply bars, registered app IDs, proposal settings with participation/approval thresholds, and a revenue split chart.
+
+### Fees Tab
+
+All fee parameters across Wallet, Social, Staking, Subscription, NFT, and Swap categories displayed side-by-side.
+
+<p align="center">
+  <img src="images/fees_view_styled.png" alt="Fees view" width="800" />
+</p>
+
+### Wallet Tab
+
+DAO wallet state, escrow accounts with balances, installed plugins with method restrictions, named plugin aliases, spending allowances, and execution keys.
+
+<p align="center">
+  <img src="images/wallet_view_styled.png" alt="Wallet view" width="800" />
+</p>
+
+### Proposals Tab
+
+Browse and inspect governance proposals. Each proposal shows its status, vote counts, and fully decoded actions — including field updates, plugin changes, and app registrations.
+
+<p align="center">
+  <img src="images/proposals_view_styled.png" alt="Proposals view" width="800" />
+</p>
+
+## CLI Commands
+
+Every view in the TUI is also available as a standalone command for scripting and CI use.
+
+### Global Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-n, --network <network>` | `mainnet`, `testnet`, or `localnet` | `mainnet` |
+| `-j, --json` | Output as JSON | off |
+
+### DAO
+
+```bash
+akita-dao info                        # quick dashboard
+akita-dao state                       # full decoded global state
+```
+
+### Proposals
+
+```bash
+akita-dao proposals list              # all proposals, newest first
+akita-dao proposals list -s active    # draft + voting only
+akita-dao proposals list -s past      # rejected, approved, executed
+akita-dao proposals list -l 5         # limit results
+akita-dao proposals get 117           # detailed view with decoded actions
+```
+
+### Wallet
+
+```bash
+akita-dao wallet info                 # wallet global state
+akita-dao wallet plugins              # installed plugins
+akita-dao wallet named-plugins        # plugin aliases
+akita-dao wallet escrows              # escrow accounts
+akita-dao wallet allowances           # spending allowances
+akita-dao wallet executions           # execution keys
+akita-dao wallet balance              # ALGO, AKTA, BONES balances
+akita-dao wallet balance 31566704     # specific asset
+akita-dao wallet balance -e rec_gov   # escrow balance
+```
+
+### JSON Output
+
+Add `--json` to any command for machine-readable output. BigInts are serialized as strings, byte arrays as hex.
+
+```bash
+akita-dao --json state
+akita-dao --json proposals list -l 10
+```
+
+### Network Switching
+
+```bash
+akita-dao -n testnet info
+akita-dao -n testnet proposals list
+```
+
+## Development
+
+```bash
+git clone https://github.com/akita-protocol/dao-cli.git
+cd dao-cli
+bun install
+bun run src/index.ts
+```
+
+Requires [akita-sdk](https://github.com/akita-protocol/akita-sc) built locally at `../../akita-sc/projects/akita-sdk`.
+
+## License
+
+MIT

package/install.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "Installing Akita DAO CLI..."
+
+# Install bun if not present
+if ! command -v bun &> /dev/null; then
+  echo "Bun not found. Installing..."
+  curl -fsSL https://bun.sh/install | bash
+  export BUN_INSTALL="$HOME/.bun"
+  export PATH="$BUN_INSTALL/bin:$PATH"
+  echo ""
+fi
+
+# Install the CLI globally
+bun add -g @akta/dao-cli
+
+echo ""
+echo "Done! Run 'akita-dao info' to get started."

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@akta/dao-cli",
+  "version": "0.1.0",
+  "description": "Read-only CLI and TUI for querying Akita DAO state on Algorand",
+  "type": "module",
+  "bin": {
+    "akita-dao": "./src/index.ts"
+  },
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@akta/sdk": "0.0.1",
+    "@algorandfoundation/algokit-utils": "9.1.2",
+    "algosdk": "3.5.2",
+    "commander": "^13.1.0",
+    "chalk": "^5.4.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "sharp": "^0.34.5",
+    "typescript": "^5.7.0"
+  },
+  "files": [
+    "src/",
+    "images/*_styled.png",
+    "install.sh"
+  ],
+  "keywords": ["algorand", "dao", "akita", "akta", "cli", "tui"],
+  "author": "Kyle Breeding",
+  "license": "MIT"
+}

package/src/commands/info.ts

@@ -0,0 +1,33 @@
+import type { AkitaDaoSDK } from "@akta/sdk";
+import { getNetworkAppIds, type AkitaNetwork } from "@akta/sdk";
+import { printJson, printKV, header } from "../output";
+
+export async function infoCommand(dao: AkitaDaoSDK, network: AkitaNetwork, json: boolean): Promise<void> {
+  const state = await dao.getGlobalState();
+  const ids = getNetworkAppIds(network);
+
+  const data = {
+    network,
+    daoAppId: dao.appId,
+    version: state.version,
+    walletAppId: state.wallet,
+    akta: state.akitaAssets?.akta,
+    bones: state.akitaAssets?.bones,
+    proposalCount: state.proposalId,
+    proposalActionLimit: state.proposalActionLimit,
+  };
+
+  if (json) return printJson(data);
+
+  header("Akita DAO");
+  printKV([
+    ["Network", network],
+    ["DAO App ID", dao.appId.toString()],
+    ["Version", state.version ?? "-"],
+    ["Wallet App ID", state.wallet?.toString() ?? "-"],
+    ["AKTA Asset ID", state.akitaAssets?.akta?.toString() ?? ids.akta.toString()],
+    ["BONES Asset ID", state.akitaAssets?.bones?.toString() ?? ids.bones.toString()],
+    ["Next Proposal ID", state.proposalId?.toString() ?? "-"],
+    ["Proposal Action Limit", state.proposalActionLimit?.toString() ?? "-"],
+  ]);
+}

package/src/commands/proposals.ts

@@ -0,0 +1,133 @@
+import type { AkitaDaoSDK } from "@akta/sdk";
+import { printJson, printColumns, header, printKV } from "../output";
+import {
+  truncateAddress,
+  formatTimestamp,
+  formatCID,
+  proposalStatusLabel,
+  proposalActionLabel,
+  formatMicroAlgo,
+  formatBigInt,
+  colorStatus,
+} from "../formatting";
+
+type StatusFilter = "all" | "active" | "past";
+
+function isActive(status: number): boolean {
+  return status === 0 || status === 20;
+}
+
+function isPast(status: number): boolean {
+  return status >= 30;
+}
+
+export async function listProposals(
+  dao: AkitaDaoSDK,
+  json: boolean,
+  statusFilter: StatusFilter = "all",
+  limit: number = 20
+): Promise<void> {
+  const proposals = await dao.client.state.box.proposals.getMap();
+
+  let entries = Array.from(proposals.entries());
+
+  if (statusFilter === "active") {
+    entries = entries.filter(([, p]) => isActive(p.status));
+  } else if (statusFilter === "past") {
+    entries = entries.filter(([, p]) => isPast(p.status));
+  }
+
+  // Sort by ID descending (newest first)
+  entries.sort((a, b) => (b[0] > a[0] ? 1 : b[0] < a[0] ? -1 : 0));
+  entries = entries.slice(0, limit);
+
+  if (json) {
+    return printJson(
+      entries.map(([id, p]) => ({
+        id,
+        status: p.status,
+        statusLabel: proposalStatusLabel(p.status),
+        creator: p.creator,
+        cid: p.cid,
+        votes: p.votes,
+        created: p.created,
+        votingTs: p.votingTs,
+        feesPaid: p.feesPaid,
+        actionCount: p.actions.length,
+      }))
+    );
+  }
+
+  header(`Proposals (${statusFilter}, showing ${entries.length})`);
+
+  if (entries.length === 0) {
+    console.log("  No proposals found.");
+    return;
+  }
+
+  const rows = entries.map(([id, p]) => [
+    id.toString(),
+    colorStatus(proposalStatusLabel(p.status)),
+    truncateAddress(p.creator),
+    `${p.votes.approvals}/${p.votes.rejections}/${p.votes.abstains}`,
+    p.actions.length.toString(),
+    formatTimestamp(p.created),
+  ]);
+
+  printColumns(["ID", "Status", "Creator", "Votes", "Actions", "Created"], rows);
+}
+
+export async function getProposal(dao: AkitaDaoSDK, id: bigint, json: boolean): Promise<void> {
+  const proposal = await dao.getProposal(id);
+
+  if (json) return printJson({ id, ...proposal });
+
+  header(`Proposal #${id}`);
+  printKV([
+    ["Status", colorStatus(proposalStatusLabel(proposal.status))],
+    ["Creator", proposal.creator],
+    ["CID", formatCID(proposal.cid)],
+    ["Created", formatTimestamp(proposal.created)],
+    ["Voting Timestamp", formatTimestamp(proposal.votingTs)],
+    ["Fees Paid", formatMicroAlgo(proposal.feesPaid)],
+  ]);
+
+  header("Votes");
+  printKV([
+    ["Approvals", formatBigInt(proposal.votes.approvals)],
+    ["Rejections", formatBigInt(proposal.votes.rejections)],
+    ["Abstains", formatBigInt(proposal.votes.abstains)],
+  ]);
+
+  if (proposal.actions.length > 0) {
+    header("Actions");
+    const rows = proposal.actions.map((action, i) => [
+      (i + 1).toString(),
+      proposalActionLabel(action.type),
+      formatActionDetails(action),
+    ]);
+    printColumns(["#", "Type", "Details"], rows);
+  }
+}
+
+function formatActionDetails(action: { type: number; [key: string]: unknown }): string {
+  const { type, ...rest } = action;
+  const parts: string[] = [];
+
+  for (const [key, value] of Object.entries(rest)) {
+    if (value instanceof Uint8Array) {
+      const hex = Buffer.from(value).toString("hex");
+      parts.push(`${key}: ${hex.length > 16 ? hex.slice(0, 16) + "..." : hex}`);
+    } else if (typeof value === "bigint") {
+      parts.push(`${key}: ${value.toString()}`);
+    } else if (typeof value === "string") {
+      parts.push(`${key}: ${value.length > 40 ? value.slice(0, 40) + "..." : value}`);
+    } else if (Array.isArray(value)) {
+      parts.push(`${key}: [${value.length} items]`);
+    } else if (value !== undefined && value !== null) {
+      parts.push(`${key}: ${String(value)}`);
+    }
+  }
+
+  return parts.join(", ");
+}

package/src/commands/state.ts

@@ -0,0 +1,167 @@
+import type { AkitaDaoSDK } from "@akta/sdk";
+import { type AkitaNetwork } from "@akta/sdk";
+import type { AkitaDaoGlobalState } from "@akta/sdk/dao";
+import { printJson, printKV, header, printColumns, printMultiColumnKV, type KVGroup } from "../output";
+import {
+  formatMicroAlgo,
+  formatBasisPoints,
+  formatDuration,
+  formatBigInt,
+  daoStateLabel,
+  resolveAppName,
+  colorState,
+} from "../formatting";
+
+export async function stateCommand(dao: AkitaDaoSDK, network: AkitaNetwork, json: boolean): Promise<void> {
+  const state = await dao.getGlobalState();
+
+  if (json) return printJson(state);
+
+  header("Core Settings");
+  printKV([
+    ["State", state.state !== undefined ? colorState(daoStateLabel(state.state)) : "-"],
+    ["Version", state.version ?? "-"],
+    ["Wallet", state.wallet ? resolveAppName(state.wallet, network) : "-"],
+    ["Proposal Action Limit", state.proposalActionLimit?.toString() ?? "-"],
+    ["Min Rewards Impact", state.minRewardsImpact?.toString() ?? "-"],
+    ["Next Proposal ID", state.proposalId?.toString() ?? "-"],
+  ]);
+
+  if (state.akitaAssets) {
+    header("Assets");
+    printKV([
+      ["AKTA", state.akitaAssets.akta.toString()],
+      ["BONES", state.akitaAssets.bones.toString()],
+    ]);
+  }
+
+  printAppLists(state, network);
+  printFees(state);
+  printProposalSettings(state);
+  printRevenueSplits(state, network);
+}
+
+function printAppLists(state: Partial<AkitaDaoGlobalState>, network: AkitaNetwork): void {
+  header("App IDs");
+
+  const sections: [string, Record<string, bigint> | undefined][] = [
+    ["Core", state.akitaAppList as Record<string, bigint> | undefined],
+    ["Social", state.akitaSocialAppList as Record<string, bigint> | undefined],
+    ["Plugins", state.pluginAppList as Record<string, bigint> | undefined],
+    ["Other", state.otherAppList as Record<string, bigint> | undefined],
+  ];
+
+  const rows: string[][] = [];
+  for (const [category, apps] of sections) {
+    if (!apps) continue;
+    for (const [, id] of Object.entries(apps)) {
+      rows.push([category, resolveAppName(id, network), id.toString()]);
+    }
+  }
+
+  printColumns(["Category", "Name", "App ID"], rows);
+}
+
+// Fields that represent basis point percentages
+const PERCENTAGE_FIELDS = new Set([
+  "referrerPercentage",
+  "impactTaxMin", "impactTaxMax",
+  "paymentPercentage", "triggerPercentage",
+  "marketplaceSalePercentageMin", "marketplaceSalePercentageMax",
+  "marketplaceComposablePercentage", "marketplaceRoyaltyDefaultPercentage",
+  "shuffleSalePercentage",
+  "auctionSaleImpactTaxMin", "auctionSaleImpactTaxMax",
+  "auctionComposablePercentage", "auctionRafflePercentage",
+  "raffleSaleImpactTaxMin", "raffleSaleImpactTaxMax",
+  "raffleComposablePercentage",
+]);
+
+// Fields that represent microAlgo fees
+const FEE_FIELDS = new Set([
+  "createFee", "creationFee", "serviceCreationFee",
+  "postFee", "reactFee",
+  "omnigemSaleFee", "auctionCreationFee", "raffleCreationFee",
+]);
+
+function formatFeeValue(key: string, value: bigint): string {
+  if (PERCENTAGE_FIELDS.has(key)) return formatBasisPoints(value);
+  if (FEE_FIELDS.has(key)) return formatMicroAlgo(value);
+  return formatBigInt(value);
+}
+
+function feeLabel(key: string): string {
+  return key
+    .replace(/([A-Z])/g, " $1")
+    .replace(/^./, (c) => c.toUpperCase())
+    .trim();
+}
+
+function printFees(state: Partial<AkitaDaoGlobalState>): void {
+  const feeGroups: [string, Record<string, bigint> | undefined][] = [
+    ["Wallet Fees", state.walletFees as Record<string, bigint> | undefined],
+    ["Social Fees", state.socialFees as Record<string, bigint> | undefined],
+    ["Staking Fees", state.stakingFees as Record<string, bigint> | undefined],
+    ["Subscription Fees", state.subscriptionFees as Record<string, bigint> | undefined],
+    ["NFT Fees", state.nftFees as Record<string, bigint> | undefined],
+    ["Swap Fees", state.swapFees as Record<string, bigint> | undefined],
+  ];
+
+  const groups: KVGroup[] = [];
+  for (const [name, fees] of feeGroups) {
+    if (!fees) continue;
+    groups.push({
+      title: name,
+      pairs: Object.entries(fees).map(([k, v]) => [feeLabel(k), formatFeeValue(k, v)]),
+    });
+  }
+
+  if (groups.length === 0) return;
+
+  header("Fees");
+  printMultiColumnKV(groups);
+}
+
+function printProposalSettings(state: Partial<AkitaDaoGlobalState>): void {
+  const settings: [string, { fee: bigint; power: bigint; duration: bigint; participation: bigint; approval: bigint } | undefined][] = [
+    ["Upgrade App", state.upgradeAppProposalSettings],
+    ["Add Plugin", state.addPluginProposalSettings],
+    ["Remove Plugin", state.removePluginProposalSettings],
+    ["Remove Execute Plugin", state.removeExecutePluginProposalSettings],
+    ["Add Allowances", state.addAllowancesProposalSettings],
+    ["Remove Allowances", state.removeAllowancesProposalSettings],
+    ["New Escrow", state.newEscrowProposalSettings],
+    ["Toggle Escrow Lock", state.toggleEscrowLockProposalSettings],
+    ["Update Fields", state.updateFieldsProposalSettings],
+  ];
+
+  const hasAny = settings.some(([, v]) => v !== undefined);
+  if (!hasAny) return;
+
+  header("Proposal Settings");
+  const rows = settings.map(([label, ps]) => {
+    if (!ps) return [label, "-", "-", "-", "-", "-"];
+    return [
+      label,
+      formatMicroAlgo(ps.fee),
+      formatBigInt(ps.power),
+      formatDuration(ps.duration),
+      formatBasisPoints(ps.participation),
+      formatBasisPoints(ps.approval),
+    ];
+  });
+  printColumns(["Category", "Fee", "Power", "Duration", "Participation", "Approval"], rows);
+}
+
+function printRevenueSplits(state: Partial<AkitaDaoGlobalState>, network: AkitaNetwork): void {
+  if (!state.revenueSplits || state.revenueSplits.length === 0) return;
+
+  header("Revenue Splits");
+  const typeLabels: Record<number, string> = { 10: "Flat", 20: "Percentage", 30: "Remainder" };
+  const rows = state.revenueSplits.map(([[wallet, escrow], type, value]) => [
+    resolveAppName(wallet, network),
+    escrow || "(default)",
+    typeLabels[type] ?? `Unknown (${type})`,
+    type === 20 ? formatBasisPoints(value) : formatBigInt(value),
+  ]);
+  printColumns(["Wallet", "Escrow", "Type", "Value"], rows);
+}