dexe-mcp 0.2.0 → 0.4.0

package/dist/tools/proposalBuildComplex.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { Interface, isAddress, ZeroAddress } from "ethers";
+import { AbiCoder, Interface, isAddress, ZeroAddress, getAddress } from "ethers";
+import { buildAddressMerkleTree } from "../lib/merkleTree.js";
 /**
  * Phase 3c — 10 complex named wrappers. Same contract as 3a/3b:
  * every wrapper returns `{ metadata, actions: Action[] }`. Actions are fed
@@ -15,10 +16,51 @@ import { Interface, isAddress, ZeroAddress } from "ethers";
 const DISTRIBUTION_PROPOSAL_ABI = [
     "function execute(uint256 proposalId, address token, uint256 amount)",
 ];
-const TOKEN_SALE_PROPOSAL_ABI = [
-    "function createTiers(tuple(tuple(string name, string description) metadata, uint256 totalTokenProvided, uint256 saleStartTime, uint256 saleEndTime, address saleTokenAddress, uint256 claimLockDuration, address[] purchaseTokenAddresses, uint256[] exchangeRates, uint256 minAllocationPerUser, uint256 maxAllocationPerUser, tuple(uint256 cliffPeriod, uint256 unlockStep, uint256 vestingDuration, uint256 vestingPercentage) vestingSettings, tuple(uint8 participationType, bytes data)[] participationDetails)[] tiers)",
+// Canonical TokenSaleProposal signatures — verified against
+// `dexe_get_methods TokenSaleProposal` (selectors createTiers=0x6a6effda,
+// addToWhitelist=0xce6c2d91, recover=0xc59b695a) and the interface at
+// `contracts/interfaces/gov/proposals/ITokenSaleProposal.sol`.
+export const TOKEN_SALE_PROPOSAL_ABI = [
+    "function createTiers(tuple(tuple(string name, string description) metadata, uint256 totalTokenProvided, uint64 saleStartTime, uint64 saleEndTime, uint64 claimLockDuration, address saleTokenAddress, address[] purchaseTokenAddresses, uint256[] exchangeRates, uint256 minAllocationPerUser, uint256 maxAllocationPerUser, tuple(uint256 vestingPercentage, uint64 vestingDuration, uint64 cliffPeriod, uint64 unlockStep) vestingSettings, tuple(uint8 participationType, bytes data)[] participationDetails)[] tiers)",
+    "function addToWhitelist(tuple(uint256 tierId, address[] users, string uri)[] requests)",
     "function recover(uint256[] tierIds)",
 ];
+const PARTICIPATION_TYPE_INDEX = {
+    DAOVotes: 0,
+    Whitelist: 1,
+    BABT: 2,
+    TokenLock: 3,
+    NftLock: 4,
+    MerkleWhitelist: 5,
+};
+const participationSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("DAOVotes"), requiredVotes: z.string() }),
+    z.object({
+        type: z.literal("Whitelist"),
+        users: z.array(z.string()).default([]),
+        uri: z.string().default(""),
+    }),
+    z.object({ type: z.literal("BABT") }),
+    z.object({
+        type: z.literal("TokenLock"),
+        token: z.string(),
+        amount: z.string(),
+    }),
+    z.object({
+        type: z.literal("NftLock"),
+        nft: z.string(),
+        amount: z.string(),
+    }),
+    z.object({
+        type: z.literal("MerkleWhitelist"),
+        users: z.array(z.string()).default([]),
+        uri: z.string().default(""),
+        root: z
+            .string()
+            .optional()
+            .describe("Optional pre-computed merkle root. If omitted but `users` is set, the tool computes it."),
+    }),
+]);
 const STAKING_PROPOSAL_ABI = [
     "function createStaking(address rewardToken, uint256 rewardAmount, uint256 startedAt, uint256 deadline, string metadata)",
 ];
@@ -31,11 +73,12 @@ const ERC20_GOV_ABI = [
     "function blacklist(address[] users, bool isBlacklisted)",
     "function transfer(address to, uint256 amount) returns (bool)",
     "function mint(address to, uint256 amount)",
+    "function approve(address spender, uint256 amount) returns (bool)",
 ];
 const ERC721_MULTIPLIER_ABI = [
-    "function setURI(uint256 tokenId, string uri)",
-    "function mint(address to, uint256 multiplier)",
-    "function mint(address to, uint256 multiplier, uint256 rewardPeriod)",
+    "function setTokenURI(uint256 tokenId, string uri)",
+    "function mint(address to, uint256 multiplier, uint256 rewardPeriod, string metadataUrl)",
+    "function changeToken(uint256 tokenId, uint256 multiplier, uint256 rewardPeriod)",
 ];
 const GOV_SETTINGS_FULL_ABI = [
     "function addSettings(tuple(bool earlyCompletion, bool delegatedVotingAllowed, bool validatorsVote, uint64 duration, uint64 durationValidators, uint64 executionDelay, uint128 quorum, uint128 quorumValidators, uint256 minVotesForVoting, uint256 minVotesForCreating, tuple(address rewardToken, uint256 creationReward, uint256 executionReward, uint256 voteRewardsCoefficient) rewardsInfo, string executorDescription)[] settings)",
@@ -67,6 +110,8 @@ function wrapperResult(params) {
 export function registerProposalBuildComplexTools(server, _ctx) {
     registerTokenDistribution(server);
     registerTokenSale(server);
+    registerTokenSaleMulti(server);
+    registerTokenSaleWhitelist(server);
     registerTokenSaleRecover(server);
     registerCreateStakingTier(server);
     registerChangeMathModel(server);
@@ -80,7 +125,7 @@ export function registerProposalBuildComplexTools(server, _ctx) {
 function registerTokenDistribution(server) {
     server.registerTool("dexe_proposal_build_token_distribution", {
         title: "Wrapper: batch token distribution via DistributionProposal",
-        description: "Builds a 'Token Distribution' external proposal. Encodes `DistributionProposal.execute(proposalId, token, amount)`. `proposalId` is the DAO's latest proposalId + 1 (distribution executes against the pending proposal number). Returns a single action; if the token is an ERC20, the agent may also need to prepend an ERC20.approve action — flagged in the nextStep hint.",
+        description: "Builds a 'Token Distribution' external proposal. Encodes `DistributionProposal.execute(proposalId, token, amount)`. For ERC20 tokens, automatically prepends an `ERC20.approve` action. For native tokens (isNative=true), sets the action value instead. `proposalId` is the DAO's latest proposalId + 1.",
         inputSchema: {
             distributionProposal: z
                 .string()
@@ -90,36 +135,48 @@ function registerTokenDistribution(server) {
                 .describe("Expected proposalId for this distribution (usually latestProposalId + 1)"),
             token: z.string(),
             amount: z.string(),
+            isNative: z.boolean().default(false).describe("True for native token (BNB/ETH) — sends value instead of approve"),
             proposalName: z.string().default("Token Distribution"),
             proposalDescription: z.string().default(""),
         },
         outputSchema: payloadOutputSchema(),
-    }, async ({ distributionProposal, proposalId, token, amount, proposalName = "Token Distribution", proposalDescription = "", }) => {
+    }, async ({ distributionProposal, proposalId, token, amount, isNative = false, proposalName = "Token Distribution", proposalDescription = "", }) => {
         if (!isAddress(distributionProposal))
             return errorResult(`Invalid distributionProposal: ${distributionProposal}`);
         if (!isAddress(token))
             return errorResult(`Invalid token: ${token}`);
         try {
-            const iface = new Interface(DISTRIBUTION_PROPOSAL_ABI);
-            const data = iface.encodeFunctionData("execute", [
+            const distIface = new Interface(DISTRIBUTION_PROPOSAL_ABI);
+            const executeData = distIface.encodeFunctionData("execute", [
                 BigInt(proposalId),
                 token,
                 BigInt(amount),
             ]);
-            const actions = [{ executor: distributionProposal, value: "0", data }];
+            const actions = [];
+            if (isNative) {
+                actions.push({ executor: distributionProposal, value: amount, data: executeData });
+            }
+            else {
+                const erc20Iface = new Interface(ERC20_GOV_ABI);
+                const approveData = erc20Iface.encodeFunctionData("approve", [distributionProposal, BigInt(amount)]);
+                actions.push({ executor: token, value: "0", data: approveData });
+                actions.push({ executor: distributionProposal, value: "0", data: executeData });
+            }
             const metadata = {
                 proposalName,
-                proposalDescription,
-                category: "Token Distribution",
+                proposalDescription: JSON.stringify(proposalDescription),
+                category: "tokenDistribution",
                 isMeta: false,
-                proposedChanges: { tokenAddress: token, tokenAmount: amount, proposalId },
-                currentChanges: {},
+                changes: {
+                    proposedChanges: { tokenAddress: token, tokenAmount: amount, proposalId },
+                    currentChanges: {},
+                },
             };
             return wrapperResult({
                 metadata,
                 actions,
                 title: `Token Distribution → ${amount} of ${token} via proposal #${proposalId}`,
-                detail: `Target: DistributionProposal(${distributionProposal}).execute\nERC20 approve may need to precede this action if token is non-native.`,
+                detail: `Target: DistributionProposal(${distributionProposal}).execute (${actions.length} actions)`,
             });
         }
         catch (err) {
@@ -128,86 +185,361 @@ function registerTokenDistribution(server) {
     });
 }
 // ---------- 2. token_sale ----------
+// Vesting settings shape — keys match the contract's VestingSettings struct
+// order (vestingPercentage, vestingDuration, cliffPeriod, unlockStep).
+const vestingSchema = z
+    .object({
+    vestingPercentage: z.string().default("0"),
+    vestingDuration: z.string().default("0"),
+    cliffPeriod: z.string().default("0"),
+    unlockStep: z.string().default("0"),
+})
+    .default({
+    vestingPercentage: "0",
+    vestingDuration: "0",
+    cliffPeriod: "0",
+    unlockStep: "0",
+});
+export const tierSchema = z.object({
+    name: z.string(),
+    description: z.string().default(""),
+    totalTokenProvided: z.string(),
+    saleStartTime: z.string().describe("Unix seconds"),
+    saleEndTime: z.string().describe("Unix seconds"),
+    claimLockDuration: z.string().default("0"),
+    saleTokenAddress: z.string(),
+    purchaseTokenAddresses: z.array(z.string()).min(1),
+    exchangeRates: z.array(z.string()).min(1),
+    minAllocationPerUser: z.string().default("0"),
+    maxAllocationPerUser: z.string().default("0"),
+    vestingSettings: vestingSchema,
+    participation: z
+        .array(participationSchema)
+        .default([])
+        .describe("Participation requirements (joined with AND on-chain). Leave empty for an open tier."),
+});
+const dataCoder = AbiCoder.defaultAbiCoder();
+function encodeParticipationData(spec) {
+    const typeIdx = PARTICIPATION_TYPE_INDEX[spec.type];
+    switch (spec.type) {
+        case "DAOVotes": {
+            const data = dataCoder.encode(["uint256"], [BigInt(spec.requiredVotes)]);
+            return { detail: { type: typeIdx, data } };
+        }
+        case "Whitelist": {
+            // Plain whitelist: NFT-mint mode. Empty data; users are added via
+            // `addToWhitelist` in a follow-up action.
+            const users = (spec.users ?? []).map((u) => {
+                if (!isAddress(u))
+                    throw new Error(`Invalid whitelist user: ${u}`);
+                return getAddress(u);
+            });
+            return {
+                detail: { type: typeIdx, data: "0x" },
+                whitelistUsers: users,
+                whitelistUri: spec.uri ?? "",
+            };
+        }
+        case "BABT": {
+            return { detail: { type: typeIdx, data: "0x" } };
+        }
+        case "TokenLock": {
+            if (!isAddress(spec.token))
+                throw new Error(`Invalid TokenLock token: ${spec.token}`);
+            const data = dataCoder.encode(["address", "uint256"], [getAddress(spec.token), BigInt(spec.amount)]);
+            return { detail: { type: typeIdx, data } };
+        }
+        case "NftLock": {
+            if (!isAddress(spec.nft))
+                throw new Error(`Invalid NftLock nft: ${spec.nft}`);
+            const data = dataCoder.encode(["address", "uint256"], [getAddress(spec.nft), BigInt(spec.amount)]);
+            return { detail: { type: typeIdx, data } };
+        }
+        case "MerkleWhitelist": {
+            let root = spec.root;
+            let users;
+            if (!root) {
+                if (!spec.users || spec.users.length === 0) {
+                    throw new Error("MerkleWhitelist needs either `root` or non-empty `users`.");
+                }
+                users = spec.users.map((u) => {
+                    if (!isAddress(u))
+                        throw new Error(`Invalid MerkleWhitelist user: ${u}`);
+                    return getAddress(u);
+                });
+                root = buildAddressMerkleTree(users).root;
+            }
+            const data = dataCoder.encode(["bytes32", "string"], [root, spec.uri ?? ""]);
+            return {
+                detail: { type: typeIdx, data },
+                derived: { root, users: users ?? [] },
+            };
+        }
+    }
+}
+export function buildTierTuple(tier) {
+    if (!isAddress(tier.saleTokenAddress)) {
+        throw new Error(`Invalid saleTokenAddress for tier "${tier.name}".`);
+    }
+    if (tier.purchaseTokenAddresses.length !== tier.exchangeRates.length) {
+        throw new Error(`Tier "${tier.name}": purchaseTokenAddresses and exchangeRates must be parallel arrays.`);
+    }
+    for (const pt of tier.purchaseTokenAddresses) {
+        if (!isAddress(pt))
+            throw new Error(`Tier "${tier.name}": invalid purchase token ${pt}.`);
+    }
+    const participationDetails = [];
+    let whitelistUsers = [];
+    let whitelistUri = "";
+    const derivedRoots = [];
+    for (const spec of tier.participation ?? []) {
+        const encoded = encodeParticipationData(spec);
+        participationDetails.push(encoded.detail);
+        if (encoded.whitelistUsers && encoded.whitelistUsers.length > 0) {
+            whitelistUsers = whitelistUsers.concat(encoded.whitelistUsers);
+            whitelistUri = encoded.whitelistUri ?? whitelistUri;
+        }
+        if (encoded.derived)
+            derivedRoots.push(encoded.derived);
+    }
+    const tuple = [
+        [tier.name, tier.description],
+        BigInt(tier.totalTokenProvided),
+        BigInt(tier.saleStartTime),
+        BigInt(tier.saleEndTime),
+        BigInt(tier.claimLockDuration),
+        getAddress(tier.saleTokenAddress),
+        tier.purchaseTokenAddresses.map((p) => getAddress(p)),
+        tier.exchangeRates.map((r) => BigInt(r)),
+        BigInt(tier.minAllocationPerUser),
+        BigInt(tier.maxAllocationPerUser),
+        [
+            BigInt(tier.vestingSettings.vestingPercentage),
+            BigInt(tier.vestingSettings.vestingDuration),
+            BigInt(tier.vestingSettings.cliffPeriod),
+            BigInt(tier.vestingSettings.unlockStep),
+        ],
+        participationDetails.map((d) => [d.type, d.data]),
+    ];
+    return { tuple, whitelistUsers, whitelistUri, derivedRoots };
+}
+export function buildSaleApprovals(tiers, tokenSaleProposal) {
+    // Sum total token provided per sale token (matches frontend's saleTokensMap
+    // reducer in `useGovPoolCreateTokenSaleProposal.ts`).
+    const totals = new Map();
+    for (const tier of tiers) {
+        const key = getAddress(tier.saleTokenAddress);
+        totals.set(key, (totals.get(key) ?? 0n) + BigInt(tier.totalTokenProvided));
+    }
+    const erc20Iface = new Interface(ERC20_GOV_ABI);
+    const actions = [];
+    for (const [token, amount] of totals.entries()) {
+        actions.push({
+            executor: token,
+            value: "0",
+            data: erc20Iface.encodeFunctionData("approve", [tokenSaleProposal, amount]),
+        });
+    }
+    return actions;
+}
+/**
+ * Pure builder for a multi-tier Token Sale proposal envelope. Used by both
+ * the `dexe_proposal_build_token_sale_multi` registrar and the OTC composite
+ * tools in `src/tools/otc.ts`.
+ */
+export function buildTokenSaleMultiActions(input) {
+    const { tokenSaleProposal, tiers, latestTierId = "0", proposalName = "Token Sale", proposalDescription = "", } = input;
+    if (!isAddress(tokenSaleProposal)) {
+        throw new Error(`Invalid tokenSaleProposal: ${tokenSaleProposal}`);
+    }
+    const iface = new Interface(TOKEN_SALE_PROPOSAL_ABI);
+    const built = tiers.map((t) => buildTierTuple(t));
+    const whitelistRequests = [];
+    const baseTierId = BigInt(latestTierId);
+    built.forEach((w, i) => {
+        if (w.whitelistUsers.length > 0) {
+            whitelistRequests.push({
+                tierId: baseTierId + 1n + BigInt(i),
+                users: w.whitelistUsers,
+                uri: w.whitelistUri,
+            });
+        }
+    });
+    const tierTuples = built.map((b) => b.tuple);
+    const createData = iface.encodeFunctionData("createTiers", [tierTuples]);
+    const actions = [];
+    actions.push(...buildSaleApprovals(tiers, tokenSaleProposal));
+    actions.push({ executor: tokenSaleProposal, value: "0", data: createData });
+    if (whitelistRequests.length > 0) {
+        const wlData = iface.encodeFunctionData("addToWhitelist", [
+            whitelistRequests.map((r) => [r.tierId, r.users, r.uri]),
+        ]);
+        actions.push({ executor: tokenSaleProposal, value: "0", data: wlData });
+    }
+    const derivedMerkleRoots = built.flatMap((b) => b.derivedRoots);
+    const metadata = {
+        proposalName,
+        proposalDescription: JSON.stringify(proposalDescription),
+        category: "tokenSale",
+        isMeta: false,
+        changes: {
+            proposedChanges: { tiers, derivedMerkleRoots },
+            currentChanges: {},
+        },
+    };
+    return {
+        metadata,
+        actions,
+        derivedMerkleRoots,
+        whitelistRequests: whitelistRequests.map((r) => ({
+            tierId: r.tierId.toString(),
+            users: r.users,
+            uri: r.uri,
+        })),
+        tierNames: tiers.map((t) => t.name).join(", "),
+    };
+}
+function registerTokenSaleMulti(server) {
+    server.registerTool("dexe_proposal_build_token_sale_multi", {
+        title: "Build a multi-tier Token Sale proposal (createTiers + optional addToWhitelist)",
+        description: "Wraps `TokenSaleProposal.createTiers([...])` for one or more tiers. Each tier may declare zero or more participation requirements (DAOVotes, Whitelist, BABT, TokenLock, NftLock, MerkleWhitelist) — the data payload is encoded per-type to match `TokenSaleProposalCreate.sol`. ERC20 approves are summed and deduped per sale token. For tiers using plain `Whitelist`, the matching `addToWhitelist` action is appended automatically when users are supplied.",
+        inputSchema: {
+            tokenSaleProposal: z.string().describe("TokenSaleProposal contract address"),
+            tiers: z.array(tierSchema).min(1),
+            latestTierId: z
+                .string()
+                .default("0")
+                .describe("Current `latestTierId()` on TokenSaleProposal. Defaults to 0 — bump when extending an existing sale so addToWhitelist tier ids are correct."),
+            proposalName: z.string().default("Token Sale"),
+            proposalDescription: z.string().default(""),
+        },
+        outputSchema: payloadOutputSchema(),
+    }, async (input) => {
+        try {
+            const built = buildTokenSaleMultiActions(input);
+            return wrapperResult({
+                metadata: built.metadata,
+                actions: built.actions,
+                title: `Token Sale tiers → ${built.tierNames}`,
+                detail: `Target: TokenSaleProposal(${input.tokenSaleProposal}).createTiers (${input.tiers.length} tier${input.tiers.length === 1 ? "" : "s"}${built.whitelistRequests.length > 0
+                    ? ` + addToWhitelist(${built.whitelistRequests.length})`
+                    : ""})`,
+            });
+        }
+        catch (err) {
+            return errorResult(err instanceof Error ? err.message : String(err));
+        }
+    });
+}
 function registerTokenSale(server) {
+    // Back-compat shim around the multi-tier builder. Same single-tier API as
+    // before, plus an optional `participation` field. Delegates encoding to
+    // `buildTierTuple` so calldata stays canonical.
     server.registerTool("dexe_proposal_build_token_sale", {
         title: "Wrapper: launch a token-sale tier via TokenSaleProposal.createTiers",
-        description: "Builds a Token Sale proposal with a single tier. Covers the common case (basic tier, optional plain whitelist, no merkle participation). For advanced merkle-whitelist tiers, encode `participationDetails` externally and use `dexe_proposal_build_custom_abi` instead.",
+        description: "Builds a Token Sale proposal with a single tier. Forwards to `dexe_proposal_build_token_sale_multi` internally. For multi-tier sales or merkle whitelists, call `_multi` directly.",
         inputSchema: {
             tokenSaleProposal: z.string().describe("TokenSaleProposal contract address"),
-            tier: z.object({
-                name: z.string(),
-                description: z.string().default(""),
-                totalTokenProvided: z.string(),
-                saleStartTime: z.string().describe("Unix seconds"),
-                saleEndTime: z.string().describe("Unix seconds"),
-                saleTokenAddress: z.string(),
-                claimLockDuration: z.string().default("0"),
-                purchaseTokenAddresses: z.array(z.string()).min(1),
-                exchangeRates: z.array(z.string()).min(1),
-                minAllocationPerUser: z.string().default("0"),
-                maxAllocationPerUser: z.string().default("0"),
-                vestingSettings: z
-                    .object({
-                    cliffPeriod: z.string().default("0"),
-                    unlockStep: z.string().default("0"),
-                    vestingDuration: z.string().default("0"),
-                    vestingPercentage: z.string().default("0"),
-                })
-                    .default({
-                    cliffPeriod: "0",
-                    unlockStep: "0",
-                    vestingDuration: "0",
-                    vestingPercentage: "0",
-                }),
-            }),
+            tier: tierSchema,
+            latestTierId: z.string().default("0"),
             proposalName: z.string().default("Token Sale"),
             proposalDescription: z.string().default(""),
         },
         outputSchema: payloadOutputSchema(),
-    }, async ({ tokenSaleProposal, tier, proposalName = "Token Sale", proposalDescription = "" }) => {
-        if (!isAddress(tokenSaleProposal))
+    }, async ({ tokenSaleProposal, tier, latestTierId = "0", proposalName = "Token Sale", proposalDescription = "", }) => {
+        if (!isAddress(tokenSaleProposal)) {
             return errorResult(`Invalid tokenSaleProposal: ${tokenSaleProposal}`);
-        if (!isAddress(tier.saleTokenAddress))
-            return errorResult(`Invalid saleTokenAddress`);
-        if (tier.purchaseTokenAddresses.length !== tier.exchangeRates.length) {
-            return errorResult("purchaseTokenAddresses and exchangeRates must be parallel arrays");
         }
         try {
             const iface = new Interface(TOKEN_SALE_PROPOSAL_ABI);
-            const tierTuple = [
-                [tier.name, tier.description],
-                BigInt(tier.totalTokenProvided),
-                BigInt(tier.saleStartTime),
-                BigInt(tier.saleEndTime),
-                tier.saleTokenAddress,
-                BigInt(tier.claimLockDuration),
-                tier.purchaseTokenAddresses,
-                tier.exchangeRates.map((r) => BigInt(r)),
-                BigInt(tier.minAllocationPerUser),
-                BigInt(tier.maxAllocationPerUser),
-                [
-                    BigInt(tier.vestingSettings.cliffPeriod),
-                    BigInt(tier.vestingSettings.unlockStep),
-                    BigInt(tier.vestingSettings.vestingDuration),
-                    BigInt(tier.vestingSettings.vestingPercentage),
-                ],
-                [], // participationDetails — empty for the common case
-            ];
-            const data = iface.encodeFunctionData("createTiers", [[tierTuple]]);
-            const actions = [{ executor: tokenSaleProposal, value: "0", data }];
+            const built = buildTierTuple(tier);
+            const actions = [];
+            actions.push(...buildSaleApprovals([tier], tokenSaleProposal));
+            actions.push({
+                executor: tokenSaleProposal,
+                value: "0",
+                data: iface.encodeFunctionData("createTiers", [[built.tuple]]),
+            });
+            if (built.whitelistUsers.length > 0) {
+                const baseTierId = BigInt(latestTierId);
+                const wlData = iface.encodeFunctionData("addToWhitelist", [
+                    [[baseTierId + 1n, built.whitelistUsers, built.whitelistUri]],
+                ]);
+                actions.push({ executor: tokenSaleProposal, value: "0", data: wlData });
+            }
             const metadata = {
                 proposalName,
-                proposalDescription,
-                category: "Token Sale",
+                proposalDescription: JSON.stringify(proposalDescription),
+                category: "tokenSale",
                 isMeta: false,
-                proposedChanges: { tier },
-                currentChanges: {},
+                changes: {
+                    proposedChanges: { tier, derivedMerkleRoots: built.derivedRoots },
+                    currentChanges: {},
+                },
             };
             return wrapperResult({
                 metadata,
                 actions,
                 title: `Token Sale tier → ${tier.name}`,
-                detail: `Target: TokenSaleProposal(${tokenSaleProposal}).createTiers (1 tier)`,
+                detail: `Target: TokenSaleProposal(${tokenSaleProposal}).createTiers (1 tier${built.whitelistUsers.length > 0 ? " + addToWhitelist" : ""})`,
+            });
+        }
+        catch (err) {
+            return errorResult(err instanceof Error ? err.message : String(err));
+        }
+    });
+}
+function registerTokenSaleWhitelist(server) {
+    server.registerTool("dexe_proposal_build_token_sale_whitelist", {
+        title: "Build an addToWhitelist proposal for existing token-sale tiers",
+        description: "Builds an external proposal calling `TokenSaleProposal.addToWhitelist([{tierId, users, uri}, ...])`. Use this to extend the whitelist of a tier that's already live (plain `Whitelist` participation type only — merkle tiers are gated by their root, not this list).",
+        inputSchema: {
+            tokenSaleProposal: z.string(),
+            requests: z
+                .array(z.object({
+                tierId: z.string(),
+                users: z.array(z.string()).min(1),
+                uri: z.string().default(""),
+            }))
+                .min(1),
+            proposalName: z.string().default("Whitelist Token Sale Tier"),
+            proposalDescription: z.string().default(""),
+        },
+        outputSchema: payloadOutputSchema(),
+    }, async ({ tokenSaleProposal, requests, proposalName = "Whitelist Token Sale Tier", proposalDescription = "", }) => {
+        if (!isAddress(tokenSaleProposal)) {
+            return errorResult(`Invalid tokenSaleProposal: ${tokenSaleProposal}`);
+        }
+        try {
+            const normalised = requests.map((r) => {
+                for (const u of r.users) {
+                    if (!isAddress(u))
+                        throw new Error(`Invalid whitelist user: ${u}`);
+                }
+                return [
+                    BigInt(r.tierId),
+                    r.users.map((u) => getAddress(u)),
+                    r.uri ?? "",
+                ];
+            });
+            const iface = new Interface(TOKEN_SALE_PROPOSAL_ABI);
+            const data = iface.encodeFunctionData("addToWhitelist", [normalised]);
+            const actions = [{ executor: tokenSaleProposal, value: "0", data }];
+            const metadata = {
+                proposalName,
+                proposalDescription: JSON.stringify(proposalDescription),
+                category: "tokenSale",
+                isMeta: false,
+                changes: {
+                    proposedChanges: { requests },
+                    currentChanges: {},
+                },
+            };
+            return wrapperResult({
+                metadata,
+                actions,
+                title: `addToWhitelist (${requests.length} request${requests.length === 1 ? "" : "s"})`,
+                detail: `Target: TokenSaleProposal(${tokenSaleProposal}).addToWhitelist`,
             });
         }
         catch (err) {
@@ -236,11 +568,13 @@ function registerTokenSaleRecover(server) {
             const actions = [{ executor: tokenSaleProposal, value: "0", data }];
             const metadata = {
                 proposalName,
-                proposalDescription,
-                category: "Recover Token Sale",
+                proposalDescription: JSON.stringify(proposalDescription),
+                category: "recoverTokenSale",
                 isMeta: false,
-                proposedChanges: { tierIds },
-                currentChanges: {},
+                changes: {
+                    proposedChanges: { tierIds },
+                    currentChanges: {},
+                },
             };
             return wrapperResult({
                 metadata,
@@ -258,7 +592,7 @@ function registerTokenSaleRecover(server) {
 function registerCreateStakingTier(server) {
     server.registerTool("dexe_proposal_build_create_staking_tier", {
         title: "Wrapper: create a staking pool/tier via StakingProposal.createStaking",
-        description: "Builds a 'Create Staking Tier' external proposal calling StakingProposal.createStaking(rewardToken, rewardAmount, startedAt, deadline, metadata).",
+        description: "Builds a 'Create Staking Tier' external proposal calling StakingProposal.createStaking(rewardToken, rewardAmount, startedAt, deadline, metadata). For ERC20 reward tokens, automatically prepends an ERC20.approve action. For native tokens (isNative=true), sets the action value instead.",
         inputSchema: {
             stakingProposal: z.string().describe("StakingProposal contract address"),
             rewardToken: z.string(),
@@ -266,38 +600,50 @@ function registerCreateStakingTier(server) {
             startedAt: z.string().describe("Unix seconds"),
             deadline: z.string().describe("Unix seconds"),
             stakingMetadataUrl: z.string().describe("ipfs://<cid> of staking-specific metadata"),
+            isNative: z.boolean().default(false).describe("True when reward token is native (BNB/ETH)"),
             proposalName: z.string().default("Create Staking"),
             proposalDescription: z.string().default(""),
         },
         outputSchema: payloadOutputSchema(),
-    }, async ({ stakingProposal, rewardToken, rewardAmount, startedAt, deadline, stakingMetadataUrl, proposalName = "Create Staking", proposalDescription = "", }) => {
+    }, async ({ stakingProposal, rewardToken, rewardAmount, startedAt, deadline, stakingMetadataUrl, isNative = false, proposalName = "Create Staking", proposalDescription = "", }) => {
         if (!isAddress(stakingProposal))
             return errorResult(`Invalid stakingProposal: ${stakingProposal}`);
         if (!isAddress(rewardToken))
             return errorResult(`Invalid rewardToken: ${rewardToken}`);
         try {
             const iface = new Interface(STAKING_PROPOSAL_ABI);
-            const data = iface.encodeFunctionData("createStaking", [
+            const createData = iface.encodeFunctionData("createStaking", [
                 rewardToken,
                 BigInt(rewardAmount),
                 BigInt(startedAt),
                 BigInt(deadline),
                 stakingMetadataUrl,
             ]);
-            const actions = [{ executor: stakingProposal, value: "0", data }];
+            const actions = [];
+            if (isNative) {
+                actions.push({ executor: stakingProposal, value: rewardAmount, data: createData });
+            }
+            else {
+                const erc20Iface = new Interface(ERC20_GOV_ABI);
+                const approveData = erc20Iface.encodeFunctionData("approve", [stakingProposal, BigInt(rewardAmount)]);
+                actions.push({ executor: rewardToken, value: "0", data: approveData });
+                actions.push({ executor: stakingProposal, value: "0", data: createData });
+            }
             const metadata = {
                 proposalName,
-                proposalDescription,
-                category: "Create Staking",
+                proposalDescription: JSON.stringify(proposalDescription),
+                category: "createStakingTier",
                 isMeta: false,
-                proposedChanges: {
-                    rewardToken,
-                    rewardAmount,
-                    startedAt,
-                    deadline,
-                    metadata: stakingMetadataUrl,
+                changes: {
+                    proposedChanges: {
+                        rewardToken,
+                        rewardAmount,
+                        startedAt,
+                        deadline,
+                        metadata: stakingMetadataUrl,
+                    },
+                    currentChanges: {},
                 },
-                currentChanges: {},
             };
             return wrapperResult({
                 metadata,
@@ -334,11 +680,13 @@ function registerChangeMathModel(server) {
             const actions = [{ executor: govPool, value: "0", data }];
             const metadata = {
                 proposalName,
-                proposalDescription,
-                category: "Change Math Model",
+                proposalDescription: JSON.stringify(proposalDescription),
+                category: "mathModel",
                 isMeta: false,
-                proposedChanges: { newVotePower },
-                currentChanges: {},
+                changes: {
+                    proposedChanges: { newVotePower },
+                    currentChanges: {},
+                },
             };
             return wrapperResult({
                 metadata,
@@ -374,11 +722,13 @@ function registerModifyDaoProfile(server) {
             const actions = [{ executor: govPool, value: "0", data }];
             const metadata = {
                 proposalName,
-                proposalDescription,
-                category: "Modify DAO Profile",
+                proposalDescription: JSON.stringify(proposalDescription),
+                category: "daoProfileModification",
                 isMeta: true,
-                proposedChanges: { descriptionUrl: newDescriptionURL },
-                currentChanges: { descriptionUrl: previousDescriptionURL ?? null },
+                changes: {
+                    proposedChanges: { descriptionUrl: newDescriptionURL },
+                    currentChanges: { descriptionUrl: previousDescriptionURL ?? null },
+                },
             };
             return wrapperResult({
                 metadata,
@@ -434,11 +784,13 @@ function registerBlacklistManagement(server) {
             }
             const metadata = {
                 proposalName,
-                proposalDescription,
-                category: "Blacklist Management",
+                proposalDescription: JSON.stringify(proposalDescription),
+                category: "blacklistManagement",
                 isMeta: false,
-                proposedChanges: { addBlacklist: addAddresses, removeBlacklist: removeAddresses },
-                currentChanges: {},
+                changes: {
+                    proposedChanges: { addBlacklist: addAddresses, removeBlacklist: removeAddresses },
+                    currentChanges: {},
+                },
             };
             return wrapperResult({
                 metadata,
@@ -456,18 +808,18 @@ function registerBlacklistManagement(server) {
 function registerRewardMultiplier(server) {
     server.registerTool("dexe_proposal_build_reward_multiplier", {
         title: "Wrapper: manage the DAO's reward-multiplier NFT contract",
-        description: "Three modes: 'set_address' (call GovPool.setNftMultiplierAddress — pass ZERO to disable), 'set_uri' (call ERC721Multiplier.setURI on a tokenId), 'mint' (call ERC721Multiplier.mint). For DeXe's global multiplier NFT, mint uses (to, multiplier, rewardPeriod); others use (to, multiplier). Set `hasRewardPeriod: true` for the 3-arg variant.",
+        description: "Four modes: 'set_address' (GovPool.setNftMultiplierAddress — ZERO to disable), 'set_token_uri' (ERC721Multiplier.setTokenURI on a tokenId), 'mint' (ERC721Multiplier.mint(to, multiplier, rewardPeriod, metadataUrl)), 'change_token' (ERC721Multiplier.changeToken(tokenId, multiplier, rewardPeriod) — modify existing NFT).",
         inputSchema: {
-            mode: z.enum(["set_address", "set_uri", "mint"]),
+            mode: z.enum(["set_address", "set_token_uri", "mint", "change_token"]),
             govPool: z.string().optional(),
             nftMultiplierContract: z.string().optional(),
             newMultiplierAddress: z.string().optional().describe("For mode=set_address"),
-            tokenId: z.string().optional().describe("For mode=set_uri"),
-            uri: z.string().optional().describe("For mode=set_uri"),
+            tokenId: z.string().optional().describe("For mode=set_token_uri or change_token"),
+            uri: z.string().optional().describe("For mode=set_token_uri"),
             to: z.string().optional().describe("For mode=mint"),
-            multiplier: z.string().optional().describe("For mode=mint"),
-            rewardPeriod: z.string().optional().describe("For mode=mint (DeXeERC721Multiplier only)"),
-            hasRewardPeriod: z.boolean().default(false),
+            multiplier: z.string().optional().describe("For mode=mint or change_token"),
+            rewardPeriod: z.string().default("0").describe("For mode=mint or change_token"),
+            metadataUrl: z.string().default("").describe("For mode=mint — metadata URI string"),
             proposalName: z.string().default("Reward Multiplier"),
             proposalDescription: z.string().default(""),
         },
@@ -489,22 +841,40 @@ function registerRewardMultiplier(server) {
                     data: iface.encodeFunctionData("setNftMultiplierAddress", [addr]),
                 });
             }
-            else if (mode === "set_uri") {
+            else if (mode === "set_token_uri") {
                 if (!input.nftMultiplierContract || !isAddress(input.nftMultiplierContract))
-                    return errorResult(`set_uri requires valid nftMultiplierContract`);
+                    return errorResult(`set_token_uri requires valid nftMultiplierContract`);
                 if (!input.tokenId)
-                    return errorResult(`set_uri requires tokenId`);
+                    return errorResult(`set_token_uri requires tokenId`);
                 if (input.uri === undefined)
-                    return errorResult(`set_uri requires uri`);
+                    return errorResult(`set_token_uri requires uri`);
                 const iface = new Interface(ERC721_MULTIPLIER_ABI);
                 actions.push({
                     executor: input.nftMultiplierContract,
                     value: "0",
-                    data: iface.encodeFunctionData("setURI", [BigInt(input.tokenId), input.uri]),
+                    data: iface.encodeFunctionData("setTokenURI", [BigInt(input.tokenId), input.uri]),
+                });
+            }
+            else if (mode === "change_token") {
+                if (!input.nftMultiplierContract || !isAddress(input.nftMultiplierContract))
+                    return errorResult(`change_token requires valid nftMultiplierContract`);
+                if (!input.tokenId)
+                    return errorResult(`change_token requires tokenId`);
+                if (!input.multiplier)
+                    return errorResult(`change_token requires multiplier`);
+                const iface = new Interface(ERC721_MULTIPLIER_ABI);
+                actions.push({
+                    executor: input.nftMultiplierContract,
+                    value: "0",
+                    data: iface.encodeFunctionData("changeToken", [
+                        BigInt(input.tokenId),
+                        BigInt(input.multiplier),
+                        BigInt(input.rewardPeriod ?? "0"),
+                    ]),
                 });
             }
             else {
-                // mint
+                // mint — 4-arg: mint(address, uint256, uint256, string)
                 if (!input.nftMultiplierContract || !isAddress(input.nftMultiplierContract))
                     return errorResult(`mint requires valid nftMultiplierContract`);
                 if (!input.to || !isAddress(input.to))
@@ -512,27 +882,26 @@ function registerRewardMultiplier(server) {
                 if (!input.multiplier)
                     return errorResult(`mint requires multiplier`);
                 const iface = new Interface(ERC721_MULTIPLIER_ABI);
-                const args = [input.to, BigInt(input.multiplier)];
-                let sig = "mint(address,uint256)";
-                if (input.hasRewardPeriod) {
-                    if (!input.rewardPeriod)
-                        return errorResult(`hasRewardPeriod requires rewardPeriod`);
-                    args.push(BigInt(input.rewardPeriod));
-                    sig = "mint(address,uint256,uint256)";
-                }
                 actions.push({
                     executor: input.nftMultiplierContract,
                     value: "0",
-                    data: iface.encodeFunctionData(sig, args),
+                    data: iface.encodeFunctionData("mint", [
+                        input.to,
+                        BigInt(input.multiplier),
+                        BigInt(input.rewardPeriod ?? "0"),
+                        input.metadataUrl ?? "",
+                    ]),
                 });
             }
             const metadata = {
                 proposalName,
-                proposalDescription,
-                category: "Reward Multiplier",
+                proposalDescription: JSON.stringify(proposalDescription),
+                category: "rewardMultiplier",
                 isMeta: false,
-                proposedChanges: { ...input, mode },
-                currentChanges: {},
+                changes: {
+                    proposedChanges: { ...input, mode },
+                    currentChanges: {},
+                },
             };
             return wrapperResult({
                 metadata,
@@ -588,11 +957,13 @@ function registerApplyToDao(server) {
             }
             const metadata = {
                 proposalName,
-                proposalDescription,
-                category: "Apply to DAO",
+                proposalDescription: JSON.stringify(proposalDescription),
+                category: "applyToDao",
                 isMeta: false,
-                proposedChanges: { receiver, tokenAmount: amount, tokenAddress: token },
-                currentChanges: { treasuryBalance },
+                changes: {
+                    proposedChanges: { receiver, tokenAmount: amount, tokenAddress: token },
+                    currentChanges: { treasuryBalance },
+                },
             };
             return wrapperResult({
                 metadata,
@@ -679,11 +1050,13 @@ function registerNewProposalType(server) {
             ];
             const metadata = {
                 proposalName,
-                proposalDescription,
-                category: "New Proposal Type",
+                proposalDescription: JSON.stringify(proposalDescription),
+                category: "createProposalType",
                 isMeta: false,
-                proposedChanges: { settings, executors, newSettingId },
-                currentChanges: {},
+                changes: {
+                    proposedChanges: { settings, executors, newSettingId },
+                    currentChanges: {},
+                },
             };
             return wrapperResult({
                 metadata,