@poa-box/core 0.1.0

package/dist/tx/vote.d.ts

@@ -0,0 +1,332 @@
+/**
+ * Vote domain tx builders — ports of the `pop vote *` write commands.
+ *
+ * Level 1 (pure, sync): buildVote, buildAnnounceWinner — plus
+ * buildGovernanceProposal in ./governance (the Level-1 builder for
+ * createProposal itself).
+ *
+ * Level 2 (resolved, async): createProposalIntent, castVoteIntent,
+ * announceWinnerIntent, executeProposalIntent, and the three governance-wrap
+ * consumers proposeQuorumIntent / proposeConfigIntent / proposeClassesIntent.
+ *
+ * Receipt parsing (parseProposalCreatedLogs lives in ./governance;
+ * parseAnnounceReceiptLogs here) and the callStatic announce probe are
+ * exported because "tx mined" is NOT success for announceWinner — the
+ * Executor swallows failed sub-calls.
+ */
+import { ethers } from 'ethers';
+import type { TxIntent } from './intent';
+import type { PopContext } from '../context';
+import { OrgModules } from '../reads/resolve';
+export type VotingType = 'hybrid' | 'dd';
+export type VotingAbiName = 'HybridVotingNew' | 'DirectDemocracyVotingNew';
+export interface VoteArgs {
+    votingAddress: string;
+    votingAbiName: VotingAbiName;
+    proposalId: ethers.BigNumberish;
+    /** Option indices voted for (must pair with weights). */
+    optionIndices: number[];
+    /** Percentage weights — the contract requires them to sum to exactly 100. */
+    weights: number[];
+    orgId?: string;
+}
+/**
+ * Port of `pop vote cast` — src/commands/vote/cast.ts:
+ * HybridVotingNew|DirectDemocracyVotingNew.vote(proposalId, optionIndices, weights).
+ */
+export declare function buildVote(a: VoteArgs): TxIntent;
+export interface AnnounceWinnerArgs {
+    votingAddress: string;
+    votingAbiName: VotingAbiName;
+    proposalId: ethers.BigNumberish;
+    orgId?: string;
+    /** meta.action override — 'announce' (default) | 'execute' | 'announce-all'. */
+    action?: string;
+}
+/**
+ * Port of `pop vote announce` / `pop vote announce-all` / `pop vote execute`
+ * — src/commands/vote/announce.ts, announce-all.ts, execute.ts:
+ * HybridVotingNew|DirectDemocracyVotingNew.announceWinner(proposalId).
+ *
+ * DESTRUCTIVE: irreversibly finalizes the vote and executes the winning
+ * option's calls through the Executor. Hosts should (a) callStatic-probe
+ * first (announceWinnerProbe) and (b) scan the receipt with
+ * parseAnnounceReceiptLogs — the outer tx can succeed while the proposal's
+ * calls reverted.
+ */
+export declare function buildAnnounceWinner(a: AnnounceWinnerArgs): TxIntent;
+/**
+ * Port of `parseAnnounceReceipt` (src/commands/vote/helpers.ts), decoupled
+ * from TxResult: takes the parsed receipt logs. The Executor catches failed
+ * sub-calls and emits CallFailed / ProposalExecutionFailed while the OUTER tx
+ * still succeeds — callers MUST treat innerFailure as an execution failure
+ * even though the transaction mined successfully.
+ */
+export declare function parseAnnounceReceiptLogs(logs: Array<{
+    name: string;
+    args?: any;
+}> | undefined | null): {
+    winningOption?: string;
+    valid?: boolean;
+    executed: boolean;
+    innerFailure: boolean;
+    failedCalls: Array<{
+        index?: string;
+        data?: string;
+    }>;
+};
+/**
+ * Port of `announceWinnerProbe` (src/commands/vote/helpers.ts): callStatic
+ * probe shared by announce/execute pre-flights — would announceWinner(id)
+ * revert right now (voting still open, already executed, quorum edge...)?
+ * Returns the decoded reason on failure. This is an RPC revert predictor:
+ * per the architecture rules it must stay RPC, never subgraph.
+ */
+export declare function announceWinnerProbe(contract: ethers.Contract, proposalId: number | string): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/**
+ * Org-module address → human name map for decoding proposal execution
+ * targets (src/commands/vote/helpers.ts MODULE_LABELS). Order matters only
+ * for display; keys come from resolveOrgModules.
+ */
+export declare const MODULE_LABELS: Array<{
+    key: keyof OrgModules;
+    label: string;
+    abi: string;
+}>;
+/** Raw execution-call input as the CLI accepts it in --calls JSON. */
+export interface ExecutionCallInput {
+    target: string;
+    value?: string | number | ethers.BigNumber;
+    data?: string;
+}
+/**
+ * Port of `describeExecutionCalls` (src/commands/vote/helpers.ts) —
+ * governance-safety decode of proposal execution calls for confirm UIs:
+ * each call's target is resolved against the org's known module addresses
+ * (named when recognized) and its calldata selector is decoded to a function
+ * signature via the known ABIs. Never throws — undecodable calls degrade to
+ * the raw selector so the human still sees SOMETHING.
+ */
+export declare function describeExecutionCalls(calls: ExecutionCallInput[], modules: Partial<OrgModules> | null | undefined): string[];
+export interface CreateProposalParams {
+    org: string;
+    type: VotingType;
+    /** Proposal title. */
+    name: string;
+    description: string;
+    durationMinutes: number;
+    optionNames: string[];
+    /**
+     * Restricted-voting hat IDs, as raw strings/BigNumbers. Hat IDs are uint256
+     * with high bits set — Number loses precision above 2^53, so entries are
+     * parsed as BigNumbers from the raw values.
+     */
+    hatIds?: Array<string | ethers.BigNumberish>;
+    /** Execution calls for option 0 ({target, value, data} — the --calls shape). */
+    calls?: ExecutionCallInput[];
+    /** Metadata createdAt override (default Date.now()). */
+    createdAt?: number;
+}
+/**
+ * Port of `pop vote create` — src/commands/vote/create.ts.
+ *
+ * Resolves the org's voting module, validates the option count, parses hat
+ * IDs as BigNumbers, applies the MAX_POLL_HATS cap check (only when
+ * ctx.provider is supplied — best-effort, exactly like the CLI: an older
+ * contract has no getter and no cap, so a failing read means the check does
+ * not apply), builds the option-0 execution batch, pins the proposal
+ * metadata {description, optionNames, createdAt}, and delegates to
+ * buildGovernanceProposal.
+ *
+ * Batch quirk preserved: with calls OMITTED the batches argument is the
+ * EMPTY array [], while calls GIVEN (even as an empty list) build per-option
+ * batches [[…], [], …] — matching the CLI's `if (argv.calls)` branch exactly.
+ */
+export declare function createProposalIntent(ctx: PopContext, params: CreateProposalParams): Promise<TxIntent>;
+export interface CastVoteParams {
+    org: string;
+    type: VotingType;
+    /** Proposal ID (number) or fuzzy title query. */
+    proposal: string | number;
+    optionIndices: number[];
+    weights: number[];
+}
+/**
+ * Port of `pop vote cast` — src/commands/vote/cast.ts.
+ *
+ * Input safety kept from the CLI: option/weight counts must match, weights
+ * must be non-negative and sum to exactly 100 (the contract's invariant) —
+ * all validated before any network traffic. The proposal argument accepts a
+ * numeric ID or fuzzy title query (resolved with preferActive: an ended
+ * homonym never shadows the one still-open match).
+ */
+export declare function castVoteIntent(ctx: PopContext, params: CastVoteParams): Promise<TxIntent>;
+export interface AnnounceWinnerParams {
+    org: string;
+    type: VotingType;
+    /** Proposal ID (number) or fuzzy title query. */
+    proposal: string | number;
+}
+/**
+ * Port of `pop vote announce` — src/commands/vote/announce.ts (also the
+ * per-proposal intent of `pop vote announce-all`).
+ *
+ * DESTRUCTIVE. This builder only resolves and encodes; the CLI's safety
+ * layers stay host-side: (1) announceWinnerProbe before broadcasting,
+ * (2) parseAnnounceReceiptLogs after — outer success + innerFailure means
+ * the proposal finalized but its execution reverted.
+ */
+export declare function announceWinnerIntent(ctx: PopContext, params: AnnounceWinnerParams): Promise<TxIntent>;
+export interface ExecuteProposalParams {
+    org: string;
+    /** Proposal ID (number) or fuzzy title query. */
+    proposal: string | number;
+}
+/**
+ * Port of `pop vote execute` — src/commands/vote/execute.ts. Hybrid-only:
+ * announceWinner is the one canonical finalize path (the Executor is
+ * allowedCaller-gated, so proposal calls cannot be executed directly).
+ *
+ * The CLI's subgraph state gate is NOT run here — hosts replicate it with
+ * reads/vote fetchProposalExecutionState + evaluateExecuteGate, then probe
+ * with announceWinnerProbe, then scan the receipt with
+ * parseAnnounceReceiptLogs (executionFailed proposals are retryable since
+ * audit H-05; the callStatic probe is the arbiter on older deployments).
+ */
+export declare function executeProposalIntent(ctx: PopContext, params: ExecuteProposalParams): Promise<TxIntent>;
+/**
+ * setConfig keys for quorum (contracts origin/main, v6):
+ *   HybridVoting: key 3 (QUORUM)
+ *   DirectDemocracyVoting: key 4 (QUORUM)
+ *
+ * The voting contracts use setConfig(uint8, bytes) instead of a direct
+ * setter, and decode the value as uint32. Since PR #119 quorum is a minimum
+ * voter COUNT (0 disables), not a percentage.
+ */
+export declare const HYBRID_QUORUM_KEY = 3;
+export declare const DD_QUORUM_KEY = 4;
+export interface ProposeQuorumParams {
+    org: string;
+    /** New quorum value (minimum voter COUNT, not a percentage). */
+    quorum: number;
+    /** Vote duration in minutes (CLI default 60). */
+    durationMinutes?: number;
+    /** Metadata createdAt override (default Date.now()). */
+    createdAt?: number;
+}
+/**
+ * Port of `pop vote propose-quorum` — src/commands/vote/propose-quorum.ts.
+ *
+ * Governance wrap: createProposal on HybridVoting with an option-0 batch of
+ * setConfig(3, abi.encode(uint32 quorum)) on HybridVoting plus
+ * setConfig(4, same) on DD when the org has one; option 1 (keep current) has
+ * no calls; hatIds [].
+ */
+export declare function proposeQuorumIntent(ctx: PopContext, params: ProposeQuorumParams): Promise<TxIntent>;
+/**
+ * ConfigKey mapping for HybridVoting (contracts origin/main, v6):
+ *   0: THRESHOLD (uint8 — support threshold percentage, 1-100)
+ *   1: TARGET_ALLOWED (deprecated — setConfig silently ignores this branch)
+ *   2: EXECUTOR (address — change the executor contract)
+ *   3: QUORUM (uint32 — minimum voter count for validity, 0 disables)
+ *
+ * ConfigKey mapping for DirectDemocracyVoting (v6):
+ *   0: THRESHOLD (uint8 — support threshold percentage, 1-100)
+ *   1: EXECUTOR (address)
+ *   2: TARGET_ALLOWED (address, bool — whitelist execution targets)
+ *   3: HAT_ALLOWED (uint256, bool — restrict voting to specific hats)
+ *   4: QUORUM (uint32 — minimum voter count for validity, 0 disables)
+ *
+ * Note: since PR #119 quorum is a voter COUNT, not a percentage.
+ */
+export interface ConfigParam {
+    name: string;
+    hybridKey: number;
+    ddKey: number | null;
+    valueType: string;
+    description: string;
+    encode: (value: string) => string;
+    validate: (value: string) => void;
+    hybridUnavailableReason?: string;
+}
+/** Port of CONFIG_PARAMS (src/commands/vote/propose-config.ts) — verbatim. */
+export declare const CONFIG_PARAMS: Record<string, ConfigParam>;
+export interface ProposeConfigParams {
+    org: string;
+    /** Configuration parameter name (a CONFIG_PARAMS key). */
+    key: string;
+    /** New value, in the key's string format. */
+    value: string;
+    /** Vote duration in minutes (CLI default 60). */
+    durationMinutes?: number;
+    /** Metadata createdAt override (default Date.now()). */
+    createdAt?: number;
+}
+/**
+ * Port of `pop vote propose-config` — src/commands/vote/propose-config.ts.
+ *
+ * Governance wrap: createProposal on HybridVoting whose option-0 batch calls
+ * setConfig(key, encodedValue) on the applicable voting contract(s) per the
+ * CONFIG_PARAMS table. Validation errors are the CLI's own (plain Error,
+ * verbatim messages).
+ */
+export declare function proposeConfigIntent(ctx: PopContext, params: ProposeConfigParams): Promise<TxIntent>;
+/** ClassStrategy enum — verified origin/main src/HybridVoting.sol. */
+export declare const CLASS_STRATEGY: {
+    readonly DIRECT: 0;
+    readonly ERC20_BAL: 1;
+};
+/** Contract constant MAX_CLASSES (origin/main src/HybridVoting.sol). */
+export declare const MAX_CLASSES = 8;
+export interface ParsedClassConfig {
+    strategy: number;
+    slicePct: number;
+    quadratic: boolean;
+    minBalance: ethers.BigNumber;
+    asset: string;
+    hatIds: ethers.BigNumber[];
+}
+/**
+ * Port of `parseClassConfigs` (src/commands/vote/classes.ts): validate +
+ * normalize a ClassConfig[] JSON document. Mirrors HybridVotingConfig
+ * setClasses validation so bad configs fail locally with a pointer to the
+ * offending class instead of a generic on-chain revert: 1..MAX_CLASSES(8)
+ * classes, each slicePct 1..100 and summing to exactly 100, ERC20_BAL needs a
+ * non-zero asset. Hat IDs are parsed as BigNumbers straight from their raw
+ * strings — real Hats IDs exceed 2^53 and would be mangled by Number.
+ */
+export declare function parseClassConfigs(doc: any): ParsedClassConfig[];
+/**
+ * Port of `describeClass` (src/commands/vote/classes.ts): one-line human
+ * description of a class (confirm summary + metadata description).
+ */
+export declare function describeClass(c: ParsedClassConfig): string;
+export interface ProposeClassesParams {
+    org: string;
+    /**
+     * The ClassConfig[] document — either the raw parsed-JSON array (host reads
+     * the file; core validates via parseClassConfigs) or an already-parsed
+     * ParsedClassConfig[].
+     */
+    classes: unknown | ParsedClassConfig[];
+    /** Vote duration in minutes (CLI default 60). */
+    durationMinutes?: number;
+    /** Metadata createdAt override (default Date.now()). */
+    createdAt?: number;
+}
+/**
+ * Port of `pop vote classes propose` — src/commands/vote/classes.ts
+ * (classesProposeHandler).
+ *
+ * setClasses(ClassConfig[]) is executor-gated on HybridVoting (verified:
+ * `function setClasses(ClassConfig[] calldata) external onlyExecutor`), so it
+ * ships as a governance proposal whose option-0 execution batch calls the
+ * voting contract through the Executor (propose-config pattern). ClassConfig
+ * tuple order: [strategy, slicePct, quadratic, minBalance, asset, hatIds].
+ */
+export declare function proposeClassesIntent(ctx: PopContext, params: ProposeClassesParams): Promise<TxIntent>;