dexe-mcp 0.4.0 → 0.5.1

package/dist/tools/predict.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolContext } from "./context.js";
+export declare function registerPredictTools(server: McpServer, ctx: ToolContext): void;
+//# sourceMappingURL=predict.d.ts.map

package/dist/tools/predict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"predict.d.ts","sourceRoot":"","sources":["../../src/tools/predict.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAiEhD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CA2K9E"}

package/dist/tools/predict.js

@@ -0,0 +1,209 @@
+import { z } from "zod";
+import { Interface, isAddress } from "ethers";
+import { RpcProvider } from "../rpc.js";
+import { multicall } from "../lib/multicall.js";
+import { gqlRequest } from "../lib/subgraph.js";
+import { proposalStateLabel } from "../lib/govEnums.js";
+/**
+ * dexe_proposal_forecast — predictive pass-rate based on historical proposals.
+ *
+ * Reads the latest 10 proposals on the DAO via getProposals + their final
+ * states, computes pass-rate + average For-vote weight, and returns a
+ * recommendation. Mainnet only — testnet has no subgraph and historical
+ * data is too sparse to forecast usefully.
+ *
+ * The "subgraph" requirement here is loose: this tool primarily runs over
+ * RPC (multicall on getProposals) so it actually works on testnet too, but
+ * we keep the documented mainnet-only contract. To opt-in on testnet, call
+ * with `forceRpcOnly: true`.
+ */
+const GOV_POOL_ABI = new Interface([
+    "function getHelperContracts() view returns (address settings, address userKeeper, address validators, address poolRegistry, address votePower)",
+    "function getProposals(uint256 offset, uint256 limit) view returns (tuple(tuple(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, uint64 voteEnd, uint64 executeAfter, bool executed, uint256 votesFor, uint256 votesAgainst, uint256 rawVotesFor, uint256 rawVotesAgainst, uint256 givenRewards) core, string descriptionURL, tuple(address executor, uint256 value, bytes data)[] actionsOnFor, tuple(address executor, uint256 value, bytes data)[] actionsOnAgainst)[] proposals, tuple(uint256 proposalId, uint256 executeAfter, uint256 quorum, uint256 rawVotesFor, uint256 rawVotesAgainst, bool executed, 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)[] validatorProposals, uint8[] proposalStates, uint256[] requiredQuorums, uint256[] requiredValidatorsQuorums)",
+]);
+const GOV_SETTINGS_ABI = new Interface([
+    "function getDefaultSettings() view returns (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))",
+]);
+// Subgraph fallback for daos with proposalCount > on-chain getProposals
+// reasonable cap. Same shape as the pools subgraph proposals entity.
+const RECENT_PROPOSALS_QUERY = /* GraphQL */ `
+  query RecentProposals($pool: String!, $first: Int!) {
+    proposals(
+      where: { pool: $pool }
+      first: $first
+      orderBy: creationTimestamp
+      orderDirection: desc
+    ) {
+      id
+      proposalId
+      executed
+      voters
+      currentRawVotesFor
+      currentRawVotesAgainst
+      quorumReached
+    }
+  }
+`;
+function err(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+function ok(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, (_k, v) => (typeof v === "bigint" ? v.toString() : v), 2),
+            },
+        ],
+    };
+}
+export function registerPredictTools(server, ctx) {
+    const rpc = new RpcProvider(ctx.config);
+    server.registerTool("dexe_proposal_forecast", {
+        title: "Predictive proposal pass-rate forecaster",
+        description: "Reads the latest 10 proposals on a DAO + their final states, computes the historical " +
+            "pass-rate and average For-vote weight, and returns a forecast. " +
+            "When `draft.actionsOnFor` is supplied the projection is annotated with the caller's vote weight. " +
+            "Mainnet only by default — pass `forceRpcOnly: true` to run on testnet using on-chain reads alone.",
+        inputSchema: {
+            govPool: z.string().describe("GovPool address"),
+            draft: z
+                .object({
+                actionsOnFor: z.array(z.unknown()).default([]),
+                voteAmount: z.string().optional(),
+            })
+                .optional()
+                .describe("Optional draft proposal — voteAmount is added to projectedFor"),
+            forceRpcOnly: z
+                .boolean()
+                .default(false)
+                .describe("Bypass mainnet-only guard; forecast purely from on-chain getProposals"),
+        },
+    }, async ({ govPool, draft, forceRpcOnly = false }) => {
+        if (!isAddress(govPool))
+            return err(`Invalid govPool: ${govPool}`);
+        const isMainnet = ctx.config.chainId === 56;
+        if (!isMainnet && !forceRpcOnly) {
+            return ok({
+                error: "subgraph required",
+                hint: "Mainnet only by default. Pass forceRpcOnly: true to run from on-chain getProposals on this chain.",
+            });
+        }
+        const provider = rpc.requireProvider();
+        // Step 1: helpers + recent 10 proposals.
+        const [helpersR, proposalsR] = await multicall(provider, [
+            { target: govPool, iface: GOV_POOL_ABI, method: "getHelperContracts", args: [], allowFailure: true },
+            { target: govPool, iface: GOV_POOL_ABI, method: "getProposals", args: [0n, 10n], allowFailure: true },
+        ]);
+        if (!helpersR?.success)
+            return err("getHelperContracts reverted");
+        const helpers = helpersR.value;
+        // Step 2: required quorum from default settings.
+        const [settingsR] = await multicall(provider, [
+            {
+                target: helpers.settings,
+                iface: GOV_SETTINGS_ABI,
+                method: "getDefaultSettings",
+                args: [],
+                allowFailure: true,
+            },
+        ]);
+        let requiredQuorum = 0n;
+        if (settingsR?.success) {
+            const s = settingsR.value;
+            requiredQuorum = s.quorum;
+        }
+        // Step 3: walk historical proposals.
+        let proposals = [];
+        if (proposalsR?.success) {
+            const raw = proposalsR.value;
+            proposals = raw.proposals.map((p, i) => {
+                const idx = Number(raw.proposalStates[i] ?? 9);
+                return {
+                    proposalId: String(i + 1),
+                    state: proposalStateLabel(idx),
+                    executed: p.core.executed,
+                    votesFor: p.core.votesFor,
+                    votesAgainst: p.core.votesAgainst,
+                };
+            });
+        }
+        // Step 4: optional subgraph cross-check for richer history (mainnet only).
+        const subgraphUrl = ctx.config.subgraphPoolsUrl;
+        let subgraphHistory = null;
+        if (subgraphUrl && isMainnet) {
+            try {
+                const data = await gqlRequest(subgraphUrl, RECENT_PROPOSALS_QUERY, {
+                    pool: govPool.toLowerCase(),
+                    first: 10,
+                });
+                subgraphHistory = data.proposals;
+            }
+            catch {
+                // soft-fail — on-chain data is enough
+            }
+        }
+        // Stats: pass-rate + average For weight.
+        const total = proposals.length;
+        const passed = proposals.filter((p) => p.state === "ExecutedFor" || p.state === "SucceededFor").length;
+        const passRate = total > 0 ? passed / total : 0;
+        const avgFor = total > 0
+            ? proposals.reduce((acc, p) => acc + p.votesFor, 0n) / BigInt(total)
+            : 0n;
+        // Projection: average + caller's draft voteAmount.
+        let projectedFor = avgFor;
+        if (draft?.voteAmount) {
+            try {
+                projectedFor += BigInt(draft.voteAmount);
+            }
+            catch {
+                // ignore malformed amount
+            }
+        }
+        const projectedPct = requiredQuorum > 0n
+            ? Number((projectedFor * 10000n) / requiredQuorum) / 100
+            : 0;
+        const hitProbability = Math.min(1, Math.max(0, projectedPct / 100));
+        // Risks heuristic.
+        const risks = [];
+        if (passRate < 0.4 && total > 0)
+            risks.push("voterApathy");
+        if ((draft?.actionsOnFor?.length ?? 0) > 5)
+            risks.push("complexityRisk");
+        if (requiredQuorum > 0n && projectedFor < requiredQuorum)
+            risks.push("quorumGap");
+        let recommendation;
+        if (hitProbability >= 0.8)
+            recommendation = "likelyPass";
+        else if (hitProbability >= 0.5)
+            recommendation = "borderline";
+        else
+            recommendation = "likelyFail";
+        return ok({
+            govPool,
+            chain: ctx.config.chainId,
+            quorum: {
+                required: requiredQuorum.toString(),
+                projectedFor: projectedFor.toString(),
+                projectedPct,
+                hitProbability,
+            },
+            historicalPassRate: {
+                last10: passed,
+                total,
+                ratio: passRate,
+            },
+            history: proposals.map((p) => ({
+                proposalId: p.proposalId,
+                state: p.state,
+                executed: p.executed,
+                votesFor: p.votesFor.toString(),
+                votesAgainst: p.votesAgainst.toString(),
+            })),
+            subgraphHistory,
+            risks,
+            recommendation,
+        });
+    });
+}
+//# sourceMappingURL=predict.js.map

package/dist/tools/predict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"predict.js","sourceRoot":"","sources":["../../src/tools/predict.ts"],"names":[],"mappings":"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"}

package/dist/tools/proposalBuildComplex.d.ts

@@ -8,7 +8,8 @@ type Action = {
     data: string;
 };
 export declare function registerProposalBuildComplexTools(server: McpServer, _ctx: ToolContext): void;
-export declare const tierSchema: z.ZodObject<{
+export declare const PRECISION_DECIMALS = 25;
+export declare const tierSchema: z.ZodEffects<z.ZodObject<{
     name: z.ZodString;
     description: z.ZodDefault<z.ZodString>;
     totalTokenProvided: z.ZodString;
@@ -17,7 +18,8 @@ export declare const tierSchema: z.ZodObject<{
     claimLockDuration: z.ZodDefault<z.ZodString>;
     saleTokenAddress: z.ZodString;
     purchaseTokenAddresses: z.ZodArray<z.ZodString, "many">;
-    exchangeRates: z.ZodArray<z.ZodString, "many">;
+    exchangeRates: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    purchaseRatios: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     minAllocationPerUser: z.ZodDefault<z.ZodString>;
     maxAllocationPerUser: z.ZodDefault<z.ZodString>;
     vestingSettings: z.ZodDefault<z.ZodObject<{
@@ -112,7 +114,6 @@ export declare const tierSchema: z.ZodObject<{
     claimLockDuration: string;
     saleTokenAddress: string;
     purchaseTokenAddresses: string[];
-    exchangeRates: string[];
     minAllocationPerUser: string;
     maxAllocationPerUser: string;
     vestingSettings: {
@@ -144,6 +145,8 @@ export declare const tierSchema: z.ZodObject<{
         users: string[];
         root?: string | undefined;
     })[];
+    exchangeRates?: string[] | undefined;
+    purchaseRatios?: string[] | undefined;
 }, {
     name: string;
     totalTokenProvided: string;
@@ -151,9 +154,94 @@ export declare const tierSchema: z.ZodObject<{
     saleEndTime: string;
     saleTokenAddress: string;
     purchaseTokenAddresses: string[];
-    exchangeRates: string[];
     description?: string | undefined;
     claimLockDuration?: string | undefined;
+    exchangeRates?: string[] | undefined;
+    purchaseRatios?: string[] | undefined;
+    minAllocationPerUser?: string | undefined;
+    maxAllocationPerUser?: string | undefined;
+    vestingSettings?: {
+        vestingPercentage?: string | undefined;
+        vestingDuration?: string | undefined;
+        cliffPeriod?: string | undefined;
+        unlockStep?: string | undefined;
+    } | undefined;
+    participation?: ({
+        type: "DAOVotes";
+        requiredVotes: string;
+    } | {
+        type: "Whitelist";
+        uri?: string | undefined;
+        users?: string[] | undefined;
+    } | {
+        type: "BABT";
+    } | {
+        type: "TokenLock";
+        token: string;
+        amount: string;
+    } | {
+        type: "NftLock";
+        amount: string;
+        nft: string;
+    } | {
+        type: "MerkleWhitelist";
+        uri?: string | undefined;
+        root?: string | undefined;
+        users?: string[] | undefined;
+    })[] | undefined;
+}>, {
+    name: string;
+    description: string;
+    totalTokenProvided: string;
+    saleStartTime: string;
+    saleEndTime: string;
+    claimLockDuration: string;
+    saleTokenAddress: string;
+    purchaseTokenAddresses: string[];
+    minAllocationPerUser: string;
+    maxAllocationPerUser: string;
+    vestingSettings: {
+        vestingPercentage: string;
+        vestingDuration: string;
+        cliffPeriod: string;
+        unlockStep: string;
+    };
+    participation: ({
+        type: "DAOVotes";
+        requiredVotes: string;
+    } | {
+        type: "Whitelist";
+        uri: string;
+        users: string[];
+    } | {
+        type: "BABT";
+    } | {
+        type: "TokenLock";
+        token: string;
+        amount: string;
+    } | {
+        type: "NftLock";
+        amount: string;
+        nft: string;
+    } | {
+        type: "MerkleWhitelist";
+        uri: string;
+        users: string[];
+        root?: string | undefined;
+    })[];
+    exchangeRates?: string[] | undefined;
+    purchaseRatios?: string[] | undefined;
+}, {
+    name: string;
+    totalTokenProvided: string;
+    saleStartTime: string;
+    saleEndTime: string;
+    saleTokenAddress: string;
+    purchaseTokenAddresses: string[];
+    description?: string | undefined;
+    claimLockDuration?: string | undefined;
+    exchangeRates?: string[] | undefined;
+    purchaseRatios?: string[] | undefined;
     minAllocationPerUser?: string | undefined;
     maxAllocationPerUser?: string | undefined;
     vestingSettings?: {

package/dist/tools/proposalBuildComplex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proposalBuildComplex.d.ts","sourceRoot":"","sources":["../../src/tools/proposalBuildComplex.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAyBhD,eAAO,MAAM,uBAAuB,yoBAI1B,CAAC;AAmFX,KAAK,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAqChE,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,WAAW,GAChB,IAAI,CAaN;AA8FD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmBrB,CAAC;AAEH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AA6ElD,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG;IAC9C,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;CACnD,CAiDA;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,iBAAiB,EAAE,MAAM,GACxB,MAAM,EAAE,CAkBV;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAChD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,GAAG;IACF,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,kBAAkB,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IACxD,iBAAiB,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtE,SAAS,EAAE,MAAM,CAAC;CACnB,CA8DA"}
+{"version":3,"file":"proposalBuildComplex.d.ts","sourceRoot":"","sources":["../../src/tools/proposalBuildComplex.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAyBhD,eAAO,MAAM,uBAAuB,yoBAI1B,CAAC;AAmFX,KAAK,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAqChE,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,WAAW,GAChB,IAAI,CAaN;AA2GD,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAGrC,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4CpB,CAAC;AAEJ,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AA6ElD,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG;IAC9C,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;CACnD,CAiGA;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,iBAAiB,EAAE,MAAM,GACxB,MAAM,EAAE,CAkBV;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAChD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,GAAG;IACF,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,kBAAkB,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IACxD,iBAAiB,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtE,SAAS,EAAE,MAAM,CAAC;CACnB,CA8DA"}

package/dist/tools/proposalBuildComplex.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { AbiCoder, Interface, isAddress, ZeroAddress, getAddress } from "ethers";
+import { AbiCoder, Interface, isAddress, ZeroAddress, getAddress, parseUnits } from "ethers";
 import { buildAddressMerkleTree } from "../lib/merkleTree.js";
 /**
  * Phase 3c — 10 complex named wrappers. Same contract as 3a/3b:
@@ -200,7 +200,23 @@ const vestingSchema = z
     cliffPeriod: "0",
     unlockStep: "0",
 });
-export const tierSchema = z.object({
+// On-chain `TokenSaleProposalBuy` formula:
+//   saleTokenAmount = purchaseAmount * PRECISION / exchangeRate
+// where PRECISION = 10**25 (see contracts/core/Globals.sol).
+//
+// Callers MUST either:
+//   - pass `exchangeRates` as raw 25-precision wei (paid_per_sold * 10^25), OR
+//   - pass `purchaseRatios` as decimal strings (e.g. "0.10" meaning
+//     0.10 purchase tokens buy 1 sale token) — auto-scaled to PRECISION.
+//
+// Any raw rate below `RATE_SUSPICION_FLOOR` is rejected with a clear hint,
+// because it almost certainly means the caller forgot the PRECISION scale
+// (a 0.10-USDT-per-token sale was misencoded as 1e17 instead of 1e24 in
+// production on 2026-05-04).
+export const PRECISION_DECIMALS = 25;
+const RATE_SUSPICION_FLOOR = 10n ** 18n;
+export const tierSchema = z
+    .object({
     name: z.string(),
     description: z.string().default(""),
     totalTokenProvided: z.string(),
@@ -209,7 +225,19 @@ export const tierSchema = z.object({
     claimLockDuration: z.string().default("0"),
     saleTokenAddress: z.string(),
     purchaseTokenAddresses: z.array(z.string()).min(1),
-    exchangeRates: z.array(z.string()).min(1),
+    exchangeRates: z
+        .array(z.string())
+        .min(1)
+        .optional()
+        .describe("Raw 25-precision rate wei (PRECISION = 10^25). On-chain: saleAmount = purchaseAmount * 1e25 / rate. " +
+        "For \"0.10 purchase per 1 sale\" pass \"1000000000000000000000000\" (= 0.10 × 10^25). " +
+        "Prefer `purchaseRatios` for human-readable input."),
+    purchaseRatios: z
+        .array(z.string())
+        .min(1)
+        .optional()
+        .describe("Human decimal ratio of purchase tokens per 1 sale token (e.g. \"0.10\" = 0.10 USDT buys 1 HELIO). " +
+        "Auto-scaled to PRECISION = 10^25. Mutually exclusive with `exchangeRates`."),
     minAllocationPerUser: z.string().default("0"),
     maxAllocationPerUser: z.string().default("0"),
     vestingSettings: vestingSchema,
@@ -217,6 +245,10 @@ export const tierSchema = z.object({
         .array(participationSchema)
         .default([])
         .describe("Participation requirements (joined with AND on-chain). Leave empty for an open tier."),
+})
+    .refine((t) => Boolean(t.exchangeRates) !== Boolean(t.purchaseRatios), {
+    message: "Provide exactly one of `exchangeRates` (raw 25-precision wei) or `purchaseRatios` (human decimals).",
+    path: ["exchangeRates"],
 });
 const dataCoder = AbiCoder.defaultAbiCoder();
 function encodeParticipationData(spec) {
@@ -281,13 +313,52 @@ 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}.`);
     }
+    // Normalize rates to raw 25-precision wei. Either branch produces a
+    // bigint[] aligned with purchaseTokenAddresses.
+    let rates;
+    if (tier.purchaseRatios) {
+        if (tier.purchaseTokenAddresses.length !== tier.purchaseRatios.length) {
+            throw new Error(`Tier "${tier.name}": purchaseTokenAddresses and purchaseRatios must be parallel arrays.`);
+        }
+        rates = tier.purchaseRatios.map((r, i) => {
+            let scaled;
+            try {
+                scaled = parseUnits(r, PRECISION_DECIMALS);
+            }
+            catch (err) {
+                throw new Error(`Tier "${tier.name}": purchaseRatios[${i}] = "${r}" is not a valid decimal.`);
+            }
+            if (scaled === 0n) {
+                throw new Error(`Tier "${tier.name}": purchaseRatios[${i}] = "${r}" resolves to 0 — rate cannot be zero.`);
+            }
+            return scaled;
+        });
+    }
+    else {
+        if (!tier.exchangeRates) {
+            throw new Error(`Tier "${tier.name}": one of \`exchangeRates\` or \`purchaseRatios\` is required.`);
+        }
+        if (tier.purchaseTokenAddresses.length !== tier.exchangeRates.length) {
+            throw new Error(`Tier "${tier.name}": purchaseTokenAddresses and exchangeRates must be parallel arrays.`);
+        }
+        rates = tier.exchangeRates.map((r, i) => {
+            const v = BigInt(r);
+            if (v === 0n) {
+                throw new Error(`Tier "${tier.name}": exchangeRates[${i}] = 0 — rate cannot be zero.`);
+            }
+            if (v < RATE_SUSPICION_FLOOR) {
+                throw new Error(`Tier "${tier.name}": exchangeRates[${i}] = ${r} looks unscaled. ` +
+                    `On-chain formula uses PRECISION = 10^25: saleAmount = purchaseAmount * 1e25 / rate. ` +
+                    `For "K purchase tokens per 1 sale token" pass K × 10^25, ` +
+                    `or use \`purchaseRatios\` with a decimal string instead.`);
+            }
+            return v;
+        });
+    }
     const participationDetails = [];
     let whitelistUsers = [];
     let whitelistUri = "";
@@ -310,7 +381,7 @@ export function buildTierTuple(tier) {
         BigInt(tier.claimLockDuration),
         getAddress(tier.saleTokenAddress),
         tier.purchaseTokenAddresses.map((p) => getAddress(p)),
-        tier.exchangeRates.map((r) => BigInt(r)),
+        rates,
         BigInt(tier.minAllocationPerUser),
         BigInt(tier.maxAllocationPerUser),
         [