@poa-box/core 0.1.0

package/dist/tx/treasury.d.ts

@@ -0,0 +1,474 @@
+/**
+ * Treasury transaction builders — ports of `pop treasury *` write paths
+ * (src/commands/treasury/).
+ *
+ * Direct writes (Level 1, PaymentManager / ERC20):
+ *   buildApproveErc20 + buildPayErc20        — pop treasury deposit (two txs)
+ *   buildClaimDistribution                   — pop treasury claim / claim-mine
+ *   buildOptOut                              — pop treasury opt-out / opt-in
+ *
+ * Governance wraps (option-0 execution batch on HybridVoting, via ./governance):
+ *   buildSendProposal                        — pop treasury send
+ *   buildDistributionProposal                — pop treasury propose-distribution
+ *   buildSwapProposal                        — pop treasury propose-swap
+ *   buildSdaiProposal                        — pop treasury propose-sdai
+ *   buildFinalizeDistributionProposal        — pop treasury propose-finalize
+ *
+ * Merkle machinery: the PT-proportional allocation + OZ StandardMerkleTree
+ * logic that was DUPLICATED between compute-merkle.ts (builder) and
+ * claim-mine.ts (reconstructor) lives here once, as pure functions.
+ */
+import { ethers } from 'ethers';
+import { StandardMerkleTree } from '@openzeppelin/merkle-tree';
+import type { TxIntent } from './intent';
+import type { PopContext } from '../context';
+/** Gnosis mainnet WXDAI/sDAI — the propose-sdai strategy is Gnosis-only. */
+export declare const GNOSIS_CHAIN_ID = 100;
+export declare const WXDAI = "0xe91D153E0b41518A2Ce8Dd3D7944Fa863463a97d";
+export declare const SDAI = "0xaf204776c7245bF4147c2612BF6e5972Ee483701";
+export interface ApproveErc20Args {
+    tokenAddress: string;
+    spender: string;
+    amountWei: ethers.BigNumberish;
+    orgId?: string;
+}
+/**
+ * Port of `pop treasury deposit` step 1 — src/commands/treasury/deposit.ts:
+ * ERC20.approve(paymentManagerAddress, amountWei).
+ */
+export declare function buildApproveErc20(a: ApproveErc20Args): TxIntent;
+export interface PayErc20Args {
+    paymentManagerAddress: string;
+    tokenAddress: string;
+    amountWei: ethers.BigNumberish;
+    orgId?: string;
+}
+/**
+ * Port of `pop treasury deposit` step 2 — src/commands/treasury/deposit.ts:
+ * PaymentManager.payERC20(token, amountWei) (pulls via transferFrom, emits
+ * PaymentReceived). DESTRUCTIVE for the depositor: withdrawing later requires
+ * a governance vote.
+ */
+export declare function buildPayErc20(a: PayErc20Args): TxIntent;
+export interface ClaimDistributionArgs {
+    paymentManagerAddress: string;
+    distributionId: ethers.BigNumberish;
+    amountWei: ethers.BigNumberish;
+    /** bytes32[] merkle proof — must hash against the raw amount exactly. */
+    proof: string[];
+    orgId?: string;
+}
+/**
+ * Port of `pop treasury claim` / `pop treasury claim-mine` —
+ * src/commands/treasury/claim.ts, claim-mine.ts:
+ * PaymentManager.claimDistribution(distId, amountWei, proof).
+ *
+ * Host-side revert predictors the CLI runs before this (deliberately NOT in
+ * the builder — they need a provider and gate broadcasting, not encoding):
+ * finalized, hasClaimed(dist, addr), isOptedOut(addr). Opt-out BLOCKS on the
+ * deployed PaymentManager (pre-L-19 vintage still reverts OptedOut).
+ */
+export declare function buildClaimDistribution(a: ClaimDistributionArgs): TxIntent;
+export interface OptOutArgs {
+    paymentManagerAddress: string;
+    /** true = opt out of distributions, false = opt back in. */
+    optOut: boolean;
+    orgId?: string;
+}
+/**
+ * Port of `pop treasury opt-out` / `pop treasury opt-in` —
+ * src/commands/treasury/opt-out.ts: PaymentManager.optOut(bool).
+ * Permissionless and idempotent; the CLI's no-op short-circuit reads
+ * isOptedOut over RPC (deliberately never the subgraph — the OptOutToggle
+ * table is empty on every live deployment AND the read gates a write).
+ */
+export declare function buildOptOut(a: OptOutArgs): TxIntent;
+export interface TreasuryRecipient {
+    to: string;
+    amount: number;
+}
+/**
+ * Parse recipients into a validated list (max 8 — the Executor batch cap).
+ * Port of parseRecipients in src/commands/treasury/send.ts; accepts the
+ * already-parsed array or the CLI's raw --recipients JSON string.
+ */
+export declare function parseRecipients(input: {
+    to?: string;
+    amount?: number;
+    recipients?: string | Array<{
+        to: string;
+        amount: number;
+    }>;
+}): TreasuryRecipient[];
+/**
+ * Validate a merkle proof array — port of the shape check in parseProof
+ * (src/commands/treasury/claim.ts), minus the fs half. Accepts the array or
+ * the CLI's inline JSON string; the allocation-object form ({ proof: [...] })
+ * is unwrapped like the CLI's --proof-file path.
+ */
+export declare function parseProof(input: string | string[] | {
+    proof: string[];
+}): string[];
+/**
+ * Convert an amount to the raw claim value: decimal token units, or raw wei
+ * with `wei`. Port of parseClaimAmount in src/commands/treasury/claim.ts.
+ * The merkle leaf hashes the raw amount, so exactness matters.
+ */
+export declare function parseClaimAmount(amount: string, wei: boolean, decimals: number): ethers.BigNumber;
+/**
+ * Merkle tree — OpenZeppelin StandardMerkleTree, matching PaymentManager on-chain.
+ *
+ * PaymentManager.claim recomputes the leaf as
+ *   keccak256(bytes.concat(keccak256(abi.encode(msg.sender, claimAmount))))
+ * and verifies it with OZ `MerkleProof.verify`, so the tree must be built exactly the way the
+ * OZ library builds it.
+ *
+ * The CLI previously used a hand-rolled tree that paired leaves left-to-right per layer and
+ * promoted an odd trailing leaf unchanged. That agrees with OZ for 1, 2, 3, 4, 6 and 8 leaves
+ * but DIVERGES at 5 and 7 (OZ builds a complete 2n-1 tree and pairs by node index). For an org
+ * with 5 or 7 members the computed root and proofs were rejected by MerkleProof.verify, so a
+ * distribution created from them could never be claimed. Pinned by
+ * test/commands/treasury-compute-merkle.test.ts. This module is the single copy that ends the
+ * builder/reconstructor drift class of bug.
+ */
+export interface DistributionMemberInput {
+    address: string;
+    /** 18-decimal wei string (subgraph participationTokenBalance). */
+    participationTokenBalance: string;
+    membershipStatus: string;
+    username?: string | null;
+}
+export interface DistributionAllocation {
+    /** EIP-55 checksummed. */
+    address: string;
+    username: string | null;
+    ptBalance: ethers.BigNumber;
+    /** Raw allocation in payout-token wei. */
+    amount: ethers.BigNumber;
+}
+/**
+ * PT-proportional allocations — the shared rule of compute-merkle.ts (builder)
+ * and claim-mine.ts (reconstructor):
+ *   - eligible = membershipStatus 'Active' AND PT > 0 AND not opted out
+ *   - allocation = totalAmount * memberPT / eligiblePT
+ *   - rounding dust goes to the FIRST member — callers must pass members
+ *     ordered by PT balance desc (both member queries do), so that is the
+ *     largest holder.
+ *
+ * Throws with the CLI's messages when no one is eligible.
+ */
+export declare function computeDistributionAllocations(members: DistributionMemberInput[], totalAmountWei: ethers.BigNumberish, optedOut?: Set<string>): DistributionAllocation[];
+/**
+ * Build the OZ StandardMerkleTree over ['address', 'uint256'] leaves —
+ * exactly what compute-merkle.ts commits and claim-mine.ts reconstructs.
+ * StandardMerkleTree hashes each value pair itself (double-keccak over
+ * abi.encode) and sorts leaves internally, so proofs are looked up by the
+ * ORIGINAL value, not by index.
+ */
+export declare function buildDistributionTree(allocations: Array<Pick<DistributionAllocation, 'address' | 'amount'>>): StandardMerkleTree<[string, string]>;
+/** Proof for one allocation — looked up by VALUE (OZ sorts leaves internally). */
+export declare function getAllocationProof(tree: StandardMerkleTree<[string, string]>, allocation: Pick<DistributionAllocation, 'address' | 'amount'>): string[];
+export interface SendProposalArgs {
+    hybridVotingAddress: string;
+    /** Validated via parseRecipients (max 8). */
+    recipients: TreasuryRecipient[];
+    /** null for the chain's native token. */
+    tokenAddress: string | null;
+    /** 18 for native; getTokenDecimals(token) otherwise — as the CLI does. */
+    decimals: number;
+    /** Native currency symbol for native sends, the token address otherwise. */
+    tokenLabel: string;
+    /** bytes32 — ipfsCidToBytes32 of the pinned proposal metadata. */
+    descriptionHash: string;
+    durationMinutes: ethers.BigNumberish;
+    orgId?: string;
+    ipfs?: {
+        cid: string;
+        metadata: unknown;
+    };
+}
+/**
+ * Port of `pop treasury send` — src/commands/treasury/send.ts.
+ * HybridVoting.createProposal wrapping an option-0 batch of at most 8 calls:
+ * native transfers as [to, amountWei, '0x'], ERC20 as
+ * [token, 0, transfer(to, amountWei)]. Option 1 is a no-op.
+ */
+export declare function buildSendProposal(a: SendProposalArgs): TxIntent;
+export interface DistributionProposalArgs {
+    hybridVotingAddress: string;
+    paymentManagerAddress: string;
+    /** As committed in merkle-distribution.json — passed through verbatim. */
+    tokenAddress: string;
+    totalAmountWei: ethers.BigNumberish;
+    merkleRoot: string;
+    checkpointBlock: ethers.BigNumberish;
+    memberCount: number;
+    /** formatUnits(totalAmountWei, payout decimals) — drives the title text. */
+    totalHuman: string;
+    descriptionHash: string;
+    durationMinutes: ethers.BigNumberish;
+    orgId?: string;
+    ipfs?: {
+        cid: string;
+        metadata: unknown;
+    };
+}
+/**
+ * Port of `pop treasury propose-distribution` —
+ * src/commands/treasury/propose-distribution.ts. HybridVoting.createProposal
+ * wrapping PaymentManager.createDistribution(payoutToken, amount, merkleRoot,
+ * checkpointBlock) — an executor-only call, hence the governance wrap.
+ * createDistribution reverts InsufficientFunds at EXECUTION time if the
+ * PaymentManager's balance can't cover total committed + this amount.
+ */
+export declare function buildDistributionProposal(a: DistributionProposalArgs): TxIntent;
+export interface SwapProposalArgs {
+    hybridVotingAddress: string;
+    paymentManagerAddress: string;
+    /** Receives the withdrawn tokens and the swap output. */
+    executorAddress: string;
+    fromToken: string;
+    poolAddress: string;
+    fromIndex: number;
+    toIndex: number;
+    /** In from-token wei. */
+    amountWei: ethers.BigNumberish;
+    /** In to-token wei — min_dy slippage guard at execution time. */
+    minOut: ethers.BigNumberish;
+    /** The human --amount figure — drives the title text. */
+    amountLabel: string | number;
+    descriptionHash: string;
+    durationMinutes: ethers.BigNumberish;
+    orgId?: string;
+    ipfs?: {
+        cid: string;
+        metadata: unknown;
+    };
+}
+/**
+ * Port of `pop treasury propose-swap` — src/commands/treasury/propose-swap.ts.
+ * HybridVoting.createProposal wrapping THREE option-0 calls:
+ *   1. PaymentManager.withdraw(fromToken, executor, amountWei)  (executor-only)
+ *   2. ERC20.approve(pool, amountWei)
+ *   3. CurvePool.exchange(int128 i, int128 j, dx, min_dy)
+ */
+export declare function buildSwapProposal(a: SwapProposalArgs): TxIntent;
+export interface SdaiProposalArgs {
+    hybridVotingAddress: string;
+    /** Receives the sDAI shares. */
+    executorAddress: string;
+    /** In xDAI wei (parseEther of the human amount). */
+    amountWei: ethers.BigNumberish;
+    /** The human --amount figure — drives the title text. */
+    amountLabel: string | number;
+    descriptionHash: string;
+    durationMinutes: ethers.BigNumberish;
+    orgId?: string;
+    ipfs?: {
+        cid: string;
+        metadata: unknown;
+    };
+}
+/**
+ * Port of `pop treasury propose-sdai` — src/commands/treasury/propose-sdai.ts.
+ * Gnosis-only (the WXDAI/SDAI constants are Gnosis mainnet deployments) —
+ * callers must enforce chainId === 100 (the Level-2 builder does).
+ * Option 0 executes three calls from the Executor:
+ *   1. [WXDAI, amountWei, deposit()]           (wraps the Executor's xDAI)
+ *   2. [WXDAI, 0, approve(SDAI, amountWei)]
+ *   3. [SDAI, 0, deposit(amountWei, executor)]
+ */
+export declare function buildSdaiProposal(a: SdaiProposalArgs): TxIntent;
+export interface FinalizeDistributionProposalArgs {
+    hybridVotingAddress: string;
+    paymentManagerAddress: string;
+    distributionId: number;
+    /**
+     * On-chain guard: execution reverts ClaimPeriodNotExpired until this many
+     * blocks have passed since the distribution's CHECKPOINT block — the
+     * DEPLOYED contract's anchor, proven by live eth_call (audit M-08's
+     * creation-block re-anchor is NOT deployed; see propose-finalize.ts).
+     */
+    minClaimPeriodBlocks: number;
+    descriptionHash: string;
+    durationMinutes: ethers.BigNumberish;
+    orgId?: string;
+    ipfs?: {
+        cid: string;
+        metadata: unknown;
+    };
+}
+/**
+ * Port of `pop treasury propose-finalize` —
+ * src/commands/treasury/propose-finalize.ts. HybridVoting.createProposal
+ * wrapping PaymentManager.finalizeDistribution(distId, minClaimPeriodBlocks)
+ * (onlyOwner = the Executor, hence the wrap). On success the unclaimed
+ * remainder returns to the Executor treasury and further claims are blocked.
+ */
+export declare function buildFinalizeDistributionProposal(a: FinalizeDistributionProposalArgs): TxIntent;
+export interface SendProposalParams {
+    org: string;
+    to?: string;
+    amount?: number;
+    recipients?: string | Array<{
+        to: string;
+        amount: number;
+    }>;
+    /** Token address or 'native' (default) for the chain's gas token. */
+    token?: string;
+    /** Vote duration in minutes (CLI default 60). */
+    durationMinutes?: number;
+}
+/**
+ * Resolved port of `pop treasury send` — src/commands/treasury/send.ts.
+ * Resolves the org's HybridVoting, derives token label/decimals, pins the
+ * proposal metadata {description, optionNames, createdAt}, and delegates to
+ * buildSendProposal.
+ */
+export declare function sendProposalIntent(ctx: PopContext, params: SendProposalParams): Promise<TxIntent>;
+/** Parsed merkle-distribution.json contents (compute-merkle output). */
+export interface MerkleDistributionData {
+    merkleRoot: string;
+    /** Raw wei string. */
+    totalAmount: string;
+    tokenAddress: string;
+    checkpointBlock: number | string;
+    memberCount: number;
+    allocations?: Array<{
+        address: string;
+        username?: string | null;
+        share?: string;
+    }>;
+}
+export interface ProposeDistributionParams {
+    org: string;
+    /** Parsed merkle-distribution.json (the CLI reads it from --merkle-file). */
+    merkle: MerkleDistributionData;
+    /** Vote duration in minutes (CLI default 1440). */
+    durationMinutes?: number;
+}
+/**
+ * Resolved port of `pop treasury propose-distribution` —
+ * src/commands/treasury/propose-distribution.ts. Takes the parsed
+ * merkle-distribution.json (file I/O stays in the host), resolves modules and
+ * payout-token decimals, pins the metadata and delegates to
+ * buildDistributionProposal. The CLI's PaymentManager-balance check is an
+ * advisory warning only (InsufficientFunds fires at execution time) and is
+ * not ported.
+ */
+export declare function proposeDistributionIntent(ctx: PopContext, params: ProposeDistributionParams): Promise<TxIntent>;
+export interface ProposeSwapParams {
+    org: string;
+    fromToken: string;
+    toToken: string;
+    /** Human units of from-token. */
+    amount: number;
+    /** Minimum output in to-token units (default: 95% of the pool quote). */
+    minOut?: number;
+    pool: string;
+    fromIndex: number;
+    toIndex: number;
+    /** Vote duration in minutes (CLI default 1440). */
+    durationMinutes?: number;
+}
+/**
+ * Resolved port of `pop treasury propose-swap` —
+ * src/commands/treasury/propose-swap.ts. Decimals come from the static
+ * known-token table only (no live read — same as the CLI); the pool quote
+ * (get_dy) requires ctx.provider and falls back exactly like the CLI when
+ * unavailable WITH a provider present: min_dy defaults to 95% of the quote,
+ * or 95% of the input when get_dy reverted — the CLI's exact fallback ladder.
+ * With NO provider and no explicit minOut this refuses instead: the CLI can
+ * never reach that state (it always has a provider), and silently deriving
+ * min_dy from the INPUT amount across a decimals mismatch would let a
+ * governance swap execute at a catastrophic rate.
+ */
+export declare function proposeSwapIntent(ctx: PopContext, params: ProposeSwapParams): Promise<TxIntent>;
+export interface ProposeSdaiParams {
+    org: string;
+    /** xDAI amount to deposit into sDAI (human units). */
+    amount: number;
+    /** Vote duration in minutes (CLI default 60). */
+    durationMinutes?: number;
+}
+/**
+ * Resolved port of `pop treasury propose-sdai` —
+ * src/commands/treasury/propose-sdai.ts. Gnosis-only. REQUIRES ctx.provider:
+ * the proposal metadata interpolates the Executor's live xDAI balance and
+ * current sDAI holdings, so the exact CLI document cannot be built without the
+ * reads. Replicates the CLI's Executor-balance precondition (execution would
+ * fail if the wrap call can't be funded).
+ */
+export declare function proposeSdaiIntent(ctx: PopContext, params: ProposeSdaiParams): Promise<TxIntent>;
+export interface ProposeFinalizeParams {
+    org: string;
+    distribution: number;
+    /** Blocks since the distribution's CHECKPOINT block before execution may succeed (CLI default 0). */
+    minClaimBlocks?: number;
+    /** Vote duration in minutes (CLI default 60). */
+    durationMinutes?: number;
+}
+/**
+ * Resolved port of `pop treasury propose-finalize` —
+ * src/commands/treasury/propose-finalize.ts. When ctx.provider is present the
+ * CLI's authoritative pre-flight runs (getDistribution →
+ * DistributionNotFound / AlreadyFinalized fail fast, and the metadata carries
+ * the payout token + unclaimed remainder); without a provider it behaves like
+ * the CLI under --no-preflight (generic 'tokens' label, no unclaimed figure).
+ */
+export declare function proposeFinalizeIntent(ctx: PopContext, params: ProposeFinalizeParams): Promise<TxIntent>;
+export interface DepositParams {
+    org: string;
+    /** ERC20 token address. */
+    token: string;
+    /** Human token units. */
+    amount: number;
+}
+/**
+ * Resolved port of `pop treasury deposit` — src/commands/treasury/deposit.ts.
+ * Returns BOTH intents of the two-transaction flow (approve, then payERC20);
+ * hosts execute them in order and stop if the approve fails. Decimals follow
+ * the CLI exactly: known-token table first (unknown tokens throw), then a
+ * live decimals()/symbol() override when a provider is available.
+ */
+export declare function depositIntents(ctx: PopContext, params: DepositParams): Promise<{
+    approve: TxIntent;
+    payERC20: TxIntent;
+    amountWei: ethers.BigNumber;
+    decimals: number;
+    symbol?: string;
+}>;
+export interface ClaimDistributionParams {
+    org: string;
+    distribution: number;
+    /** Decimal token units by default; the exact raw integer with wei=true. */
+    amount: string;
+    wei?: boolean;
+    /** Merkle proof — array, inline JSON string, or allocation object. */
+    proof: string | string[] | {
+        proof: string[];
+    };
+}
+/**
+ * Resolved port of `pop treasury claim` — src/commands/treasury/claim.ts.
+ * Resolves the payout token's decimals subgraph-FIRST (FETCH_DISTRIBUTION_BY_ID
+ * — null means "not indexed yet" and falls through to getDistribution() when a
+ * provider is available, never DistributionNotFound), converts the amount with
+ * parseClaimAmount, and delegates to buildClaimDistribution.
+ *
+ * The CLI's revert-predicting pre-flight (finalized / hasClaimed / isOptedOut
+ * — all authoritative eth_calls) stays host-side; opt-out BLOCKS on the
+ * deployed pre-L-19 PaymentManager.
+ */
+export declare function claimDistributionIntent(ctx: PopContext, params: ClaimDistributionParams): Promise<TxIntent>;
+export interface OptOutParams {
+    org: string;
+    /** true = opt out, false = opt back in. */
+    optOut: boolean;
+}
+/**
+ * Resolved port of `pop treasury opt-out` / `opt-in` —
+ * src/commands/treasury/opt-out.ts. The CLI's isOptedOut no-op short-circuit
+ * is a host-side pre-flight (the call is idempotent on-chain anyway).
+ */
+export declare function optOutIntent(ctx: PopContext, params: OptOutParams): Promise<TxIntent>;