DAO 治理

interface VotingPower {
  tokenPower: number;            // sqrt(stakedTokens)
  lockupMultiplier: number;      // 1.0 – 2.0
  reputationMultiplier: number;  // 0.8 – 1.5
  delegatedPower: number;        // Received from delegators
  totalPower: number;            // Computed composite
}

const PROPOSAL_TYPES = [
  'parameter_change',     // Adjust protocol parameters
  'treasury_spend',       // Allocate treasury funds
  'protocol_upgrade',     // Upgrade smart contracts
  'emergency',            // Emergency security actions
  'signal',               // Non-binding sentiment poll
] as const;
type ProposalType = (typeof PROPOSAL_TYPES)[number];

const PROPOSAL_STATUSES = [
  'draft',        // Created but not yet submitted
  'discussion',   // In discussion period
  'voting',       // Voting is active
  'passed',       // Vote passed, awaiting timelock queue
  'rejected',     // Vote failed (threshold not met)
  'queued',       // In timelock queue, awaiting execution
  'executed',     // Successfully executed
  'expired',      // Quorum not reached within voting period
  'vetoed',       // Blocked by emergency council
] as const;

interface Proposal {
  id: string;
  proposer: string;                     // DID of the proposer
  type: ProposalType;
  title: string;
  description: string;                  // Detailed proposal description (Markdown)
  discussionUrl?: string;               // Link to forum discussion
  actions: ProposalAction[];            // On-chain actions to execute
  timeline: ProposalTimeline;
  votes: ProposalVotes;                 // Aggregated vote tallies
  status: ProposalStatus;
  resourcePrev?: string | null;         // Event-sourced chain reference
}

interface ProposalTimeline {
  createdAt: number;
  discussionEndsAt: number;
  votingStartsAt: number;
  votingEndsAt: number;
  executionDelay: number;               // Timelock duration (ms)
  expiresAt: number;
}

interface ProposalVotes {
  for: string;       // Total voting power "for" (bigint as string)
  against: string;   // Total voting power "against"
  abstain: string;   // Total voting power "abstain"
}

interface ParameterChangeAction {
  type: 'parameter_change';
  target: string;              // Parameter key (e.g., "marketFeePercent")
  currentValue: unknown;       // Current value for transparency
  newValue: unknown;           // Proposed new value
}

interface TreasurySpendAction {
  type: 'treasury_spend';
  recipient: string;           // DID or address of the recipient
  amount: string;              // Token amount
  token: string;               // Always "TOKEN" currently
  purpose: string;             // Description of why funds are needed
  vestingSchedule?: {
    cliff: number;             // Cliff period before any release (ms)
    duration: number;          // Total vesting duration (ms)
    interval: number;          // Release interval (ms)
  };
}

interface ContractUpgradeAction {
  type: 'contract_upgrade';
  contract: string;            // Contract name (e.g., "ClawToken", "ClawEscrow")
  newImplementation: string;   // Address of the new implementation contract
  migrationData?: string;      // Calldata for upgradeToAndCall (migration logic)
}

interface EmergencyAction {
  type: 'emergency';
  action: 'pause' | 'unpause' | 'upgrade';
  target: string;              // Contract or system to act on
  reason: string;              // Justification for emergency action
}

const VOTE_OPTIONS = ['for', 'against', 'abstain'] as const;
type VoteOption = (typeof VOTE_OPTIONS)[number];

interface Vote {
  voter: string;            // Voter's DID
  proposalId: string;
  option: VoteOption;       // for | against | abstain
  power: string;            // Voting power at time of vote (bigint as string)
  reason?: string;          // Optional: explanation of vote
  ts: number;               // Timestamp
  hash: string;             // Event hash for deduplication
}

interface Delegation {
  delegator: string;           // DID of the agent delegating power
  delegate: string;            // DID of the agent receiving power
  scope: DelegationScope;      // What types of proposals this covers
  percentage: number;          // 0–100: what fraction of power to delegate
  expiresAt?: number;          // Optional expiry
  revokedAt?: number;          // Set when delegation is revoked
  createdAt: number;
}

interface DelegationScope {
  proposalTypes?: ProposalType[];  // Limit to specific proposal types
  topics?: string[];               // Limit to specific topics
  all?: boolean;                   // Delegate for all proposals
}

interface Treasury {
  balance: string;                           // Current balance (bigint as string)
  allocationPolicy: TreasuryAllocationPolicy;
  spendingLimits: TreasurySpendingLimits;
  totalSpent: string;
  spentThisQuarter: string;
  quarterStart: number;
}

interface TreasuryAllocationPolicy {
  development: number;     // % allocated to protocol development
  nodeRewards: number;     // % allocated to node operator rewards
  ecosystem: number;       // % allocated to ecosystem grants
  reserve: number;         // % kept in reserve
}

interface TreasurySpendingLimits {
  perProposal: string;     // Max spend per single proposal
  perQuarter: string;      // Max cumulative spend per quarter
  requireMultisig: string; // Amount above which multisig co-sign is required
}

type TimelockStatus = 'queued' | 'executed' | 'cancelled';

interface TimelockEntry {
  actionId: string;
  proposalId: string;
  action: ProposalAction;          // The specific action to execute
  queuedAt: number;
  executeAfter: number;            // Earliest execution timestamp
  status: TimelockStatus;
}

const DEFAULT_GOVERNANCE_PARAMS: GovernanceParams = {
  proposalThreshold: 0.001,     // 0.1% of supply to create proposals
  quorum: 0.04,                 // 4% participation required
  votingDelay: 2 * DAY_MS,      // 2-day discussion period
  votingPeriod: 3 * DAY_MS,     // 3-day voting window
  timelockDelay: 1 * DAY_MS,    // 1-day execution delay
  passThreshold: 0.5,           // 50% "for" votes required
};