dexe-otc
An OTC DAO sells its own token via on-chain TokenSaleProposal tiers. Each step
is one MCP call; calldata broadcasts when a signer is connected (WalletConnect,
keystore, or DEXE_SIGNER_MODE=unattended + DEXE_PRIVATE_KEY).
Validate on BSC testnet (chain 97) first. Full recipe + runnable proof:
docs/OTC.md and scripts/lifecycle-otc.mjs.
The three composites and two reads
The two reads were dexe_otc_list_sales_for_dao and dexe_otc_buyer_status
before 0.36.0; the old names still answer as deprecated aliases.
| Tool |
Role |
dexe_otc_dao_open_sale |
multi-tier createTiers envelope + IPFS metadata + deposit + createProposalAndVote. buildOnly:true returns just the envelope. |
dexe_read_token_sales |
list a DAO's tiers (prices, totalSold, isOff, UTC times). |
dexe_read_token_sale_position |
render-ready buyer view: prices, claimable, vesting, auto-merkle proof. |
dexe_otc_buyer_buy |
preflight balance/allowance + approve + buy(); native path uses the sentinel + value. |
dexe_otc_buyer_claim_all |
claims tiers with canClaim && !isClaimed, withdraws vested; noop when nothing pending. |
Owner flow
dexe_dao_predict_addresses → get govPool / govToken / govTokenSale.
- Deploy with treasury pre-seeded (mint to the predicted
govPool via
tokenParams.users[]) — see [[dexe-create-dao]].
dexe_otc_dao_open_sale with tiers (schema below).
- Poll
dexe_proposal_state until SucceededFor (index 4; it briefly sits in
Locked=6), then dexe_vote_build_execute → broadcast.
Buyer flow
dexe_read_token_sale_position → dexe_otc_buyer_buy → (after the sale window closes)
dexe_otc_buyer_claim_all.
Critical gotchas
- Buyer amounts accept human units — a decimal string (
"50.0") is scaled
by the token's real on-chain decimals; digits-only stays raw wei.
dexe_otc_buyer_buy converts the 18-dec-normalized buy amount to the
payment token's native decimals for the balance check and the exact
approve — no silent under-pay on <18-dec payment tokens.
- Exchange rate is PRECISION 1e25, not 1e18. 1:1 =
"10000000000000000000000000".
- Native BNB =
0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE (ETHEREUM_ADDRESS),
never 0x0…0 — a zero-address purchase token makes the tier unbuyable. Buy
tools accept 0x0 as an alias but emit the sentinel.
canClaim needs block.timestamp ≥ saleEndTime + claimLockDuration — buyers
wait for the window to close even when claimLockDuration:0.
maxAllocationPerUser == 0 means unlimited, not zero — set a real cap.
- Treasury must hold the sale token before the sale opens — pre-seed at deploy.
vestingPercentage is a human percent 0–100 (auto-scaled by 1e25).
- Merkle tiers need the whitelist JSON on IPFS;
open_sale auto-uploads when
uri is empty (needs DEXE_PINATA_JWT). Roots via dexe_merkle_build.
Tier schema (abridged)
{
"name": "Public Tier 1", "description": "",
"totalTokenProvided": "<wei>",
"saleStartTime": "<unix sec>", "saleEndTime": "<unix sec>", "claimLockDuration": "0",
"saleTokenAddress": "0x…",
"purchaseTokenAddresses": ["0xEeee…EEeE"], // native, or ERC20 addresses
"exchangeRates": ["10000000000000000000000000"],
"minAllocationPerUser": "0", "maxAllocationPerUser": "<wei, non-zero>",
"vestingSettings": { "vestingPercentage": "0", "vestingDuration": "0", "cliffPeriod": "0", "unlockStep": "0" },
"participation": [] // AND-list; empty = open tier
}
Do not modify OTC tool behavior lightly — the v0.11.x OTC surface is validated
E2E on mainnet. See docs/OTC.md for the exhaustive reference.
Canonical recipe (generated from src/knowledge/ — edit there, then npm run gen:knowledge)
Open an OTC / token sale (otc_sale)
Open a multi-tier token sale (proposal → vote → execute → live), then buyers check status / buy / claim via the dexe_otc_* composites.
Ask the user:
govPool — Which DAO (govPool address)?
saleTokenAmount — How many DAO tokens to sell in this tier? · ⚠ This amount moves from the treasury into the sale at execute.
price — Price per DAO token, and in which purchase token (address, or native BNB)? · ⚠ Rates are stored ×1e25 on-chain — always pass human units and let the composite scale; a mis-scaled hand-made rate can sell the allocation for pennies.
saleWindow — Sale start and end times? (ask in the user's words — e.g. 'starts tomorrow, runs 7 days' — then compute Unix seconds from the CURRENT time; never guess the date) · ⚠ The window must be in the future at EXECUTE time (add voting-period headroom). A past window creates a dead tier — every buy reverts.
vesting (optional) — Vesting? (RECOMMEND 0 on newly deployed DAOs — vested funds are currently unrecoverable there) · default 0 · ⚠ vestingWithdraw is blocked by SphereX on fresh pools — a non-zero vestingPercentage strands the vested portion (confirmed protocol bug).
whitelist (optional) — Open to everyone, or a whitelist of addresses?
Steps:
dexe_otc_dao_open_sale — Build + create the TokenSaleProposal tiers proposal (auto-uploads merkle whitelist JSON if given).
dexe_proposal_vote_and_execute — Vote + execute the sale proposal — the tier goes live at execute.
dexe_read_token_sales — Confirm the tier is live and show its parameters (times are UTC).
Pitfalls (danger first):
- 🔴 TokenSaleProposal.vestingWithdraw is blocked ('SphereX error: disallowed tx pattern') in EVERY call shape on fresh pools — the VESTED portion of a purchase CANNOT be withdrawn (confirmed protocol bug, escalated upstream). Until fixed: open tiers with vestingPercentage:"0" on new DAOs. claim (the instant portion) works fine.
- 🔴 NEVER guess dates for sale/staking windows — compute Unix timestamps from the CURRENT time (ask the user or read the latest block; your idea of 'now' may be a stale year). Windows must be in the future AT EXECUTE TIME (add headroom for the voting period). A staking tier with a past deadline is SILENTLY rejected on-chain (the execute succeeds, a StakingRejected event fires, NO tier exists, the reward bounces back); a sale tier with a past window is created dead-on-arrival (every buy reverts 'TSP: token sale is over'). The builders refuse past end-times before any transaction.
- ⚠ Native BNB in sale tiers uses the sentinel address 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE, NOT the zero address (0x0 reverts 'TSP: incorrect token'). A native-currency buy must send msg.value equal to the buy amount. The dexe_otc_* composites canonicalize this.
- ⚠ Tier exchange rates are scaled ×1e25 (PRECISION) on-chain. Pass human units to the dexe_otc_* composites and they scale for you; only ADVANCED raw structs need pre-scaled values. A hand-scaled rate off by 10^2 sells the whole allocation for pennies.
- ℹ Whitelisted tiers use a merkle root; the tier's uri must point to IPFS JSON {"list":[lowercased addresses]} so buyers can regenerate proofs — dexe_otc_dao_open_sale auto-uploads it when uri is empty (needs DEXE_PINATA_JWT). Buyer-side reads need the proof BEFORE getUserViews or canParticipate reads false.
- ℹ Amount strings: digits-only = RAW smallest units (wei); a decimal point ("12.5") = human units scaled by the token's REAL on-chain decimals (never assumed 18). Durations and delays are SECONDS (86400 = 1 day). Composite quorum/percent params are plain percent numbers (51).
For the machine-readable plan (interview questions with risk notes, step templates with flowContext chaining), call the dexe_guide tool with flow:"otc_sale".
1---2name: dexe-otc3description: |4 Run a DeXe OTC token sale end-to-end — open a multi-tier TokenSaleProposal,5 vote+execute it, then buyers check status / buy / claim. Covers the three6 dexe_otc_* composites and the two token-sale reads, plus the PRECISION-1e25 rate, native-BNB sentinel, and7 claim-timing gotchas. Use when the user mentions "OTC", "token sale", "sell DAO8 tokens", "buy from a tier", "claim vested tokens".9metadata:10 source: https://skillmd.com/skills/jiayaoqijia/dexe-otc11---1213# dexe-otc1415An OTC DAO sells its own token via on-chain `TokenSaleProposal` tiers. Each step16is one MCP call; calldata broadcasts when a signer is connected (WalletConnect,17keystore, or `DEXE_SIGNER_MODE=unattended` + `DEXE_PRIVATE_KEY`).18Validate on **BSC testnet (chain 97)** first. Full recipe + runnable proof:19`docs/OTC.md` and `scripts/lifecycle-otc.mjs`.2021## The three composites and two reads2223The two reads were `dexe_otc_list_sales_for_dao` and `dexe_otc_buyer_status`24before 0.36.0; the old names still answer as deprecated aliases.2526| Tool | Role |27|---|---|28| `dexe_otc_dao_open_sale` | multi-tier `createTiers` envelope + IPFS metadata + deposit + `createProposalAndVote`. `buildOnly:true` returns just the envelope. |29| `dexe_read_token_sales` | list a DAO's tiers (prices, `totalSold`, `isOff`, UTC times). |30| `dexe_read_token_sale_position` | render-ready buyer view: prices, claimable, vesting, auto-merkle proof. |31| `dexe_otc_buyer_buy` | preflight balance/allowance + approve + `buy()`; native path uses the sentinel + `value`. |32| `dexe_otc_buyer_claim_all` | claims tiers with `canClaim && !isClaimed`, withdraws vested; `noop` when nothing pending. |3334## Owner flow35361. `dexe_dao_predict_addresses` → get `govPool` / `govToken` / `govTokenSale`.372. Deploy with treasury pre-seeded (mint to the predicted `govPool` via38 `tokenParams.users[]`) — see [[dexe-create-dao]].393. `dexe_otc_dao_open_sale` with tiers (schema below).404. Poll `dexe_proposal_state` until `SucceededFor` (index 4; it briefly sits in41 `Locked`=6), then `dexe_vote_build_execute` → broadcast.4243## Buyer flow4445`dexe_read_token_sale_position` → `dexe_otc_buyer_buy` → (after the sale window closes)46`dexe_otc_buyer_claim_all`.4748## Critical gotchas4950- **Buyer amounts accept human units** — a decimal string (`"50.0"`) is scaled51 by the token's real on-chain decimals; digits-only stays raw wei.52 `dexe_otc_buyer_buy` converts the 18-dec-normalized buy amount to the53 **payment token's native decimals** for the balance check and the exact54 approve — no silent under-pay on <18-dec payment tokens.55- **Exchange rate is PRECISION 1e25**, not 1e18. 1:1 = `"10000000000000000000000000"`.56- **Native BNB = `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`** (ETHEREUM_ADDRESS),57 never `0x0…0` — a zero-address purchase token makes the tier unbuyable. Buy58 tools accept `0x0` as an alias but emit the sentinel.59- **`canClaim` needs `block.timestamp ≥ saleEndTime + claimLockDuration`** — buyers60 wait for the window to close even when `claimLockDuration:0`.61- **`maxAllocationPerUser == 0` means unlimited**, not zero — set a real cap.62- **Treasury must hold the sale token before the sale opens** — pre-seed at deploy.63- **`vestingPercentage` is a human percent 0–100** (auto-scaled by 1e25).64- **Merkle tiers** need the whitelist JSON on IPFS; `open_sale` auto-uploads when65 `uri` is empty (needs `DEXE_PINATA_JWT`). Roots via `dexe_merkle_build`.6667## Tier schema (abridged)6869```jsonc70{71 "name": "Public Tier 1", "description": "",72 "totalTokenProvided": "<wei>",73 "saleStartTime": "<unix sec>", "saleEndTime": "<unix sec>", "claimLockDuration": "0",74 "saleTokenAddress": "0x…",75 "purchaseTokenAddresses": ["0xEeee…EEeE"], // native, or ERC20 addresses76 "exchangeRates": ["10000000000000000000000000"],77 "minAllocationPerUser": "0", "maxAllocationPerUser": "<wei, non-zero>",78 "vestingSettings": { "vestingPercentage": "0", "vestingDuration": "0", "cliffPeriod": "0", "unlockStep": "0" },79 "participation": [] // AND-list; empty = open tier80}81```8283Do not modify OTC tool behavior lightly — the v0.11.x OTC surface is validated84E2E on mainnet. See `docs/OTC.md` for the exhaustive reference.8586## Canonical recipe (generated from src/knowledge/ — edit there, then `npm run gen:knowledge`)8788<!-- BEGIN GENERATED: flow-recipe -->89### Open an OTC / token sale (`otc_sale`)9091Open a multi-tier token sale (proposal → vote → execute → live), then buyers check status / buy / claim via the dexe_otc_* composites.9293**Ask the user:**94- `govPool` — Which DAO (govPool address)?95- `saleTokenAmount` — How many DAO tokens to sell in this tier? · ⚠ This amount moves from the treasury into the sale at execute.96- `price` — Price per DAO token, and in which purchase token (address, or native BNB)? · ⚠ Rates are stored ×1e25 on-chain — always pass human units and let the composite scale; a mis-scaled hand-made rate can sell the allocation for pennies.97- `saleWindow` — Sale start and end times? (ask in the user's words — e.g. 'starts tomorrow, runs 7 days' — then compute Unix seconds from the CURRENT time; never guess the date) · ⚠ The window must be in the future at EXECUTE time (add voting-period headroom). A past window creates a dead tier — every buy reverts.98- `vesting` (optional) — Vesting? (RECOMMEND 0 on newly deployed DAOs — vested funds are currently unrecoverable there) · default `0` · ⚠ vestingWithdraw is blocked by SphereX on fresh pools — a non-zero vestingPercentage strands the vested portion (confirmed protocol bug).99- `whitelist` (optional) — Open to everyone, or a whitelist of addresses?100101**Steps:**1021. `dexe_otc_dao_open_sale` — Build + create the TokenSaleProposal tiers proposal (auto-uploads merkle whitelist JSON if given).1032. `dexe_proposal_vote_and_execute` — Vote + execute the sale proposal — the tier goes live at execute.1043. `dexe_read_token_sales` — Confirm the tier is live and show its parameters (times are UTC).105106**Pitfalls (danger first):**107- 🔴 TokenSaleProposal.vestingWithdraw is blocked ('SphereX error: disallowed tx pattern') in EVERY call shape on fresh pools — the VESTED portion of a purchase CANNOT be withdrawn (confirmed protocol bug, escalated upstream). Until fixed: open tiers with vestingPercentage:"0" on new DAOs. claim (the instant portion) works fine.108- 🔴 NEVER guess dates for sale/staking windows — compute Unix timestamps from the CURRENT time (ask the user or read the latest block; your idea of 'now' may be a stale year). Windows must be in the future AT EXECUTE TIME (add headroom for the voting period). A staking tier with a past deadline is SILENTLY rejected on-chain (the execute succeeds, a StakingRejected event fires, NO tier exists, the reward bounces back); a sale tier with a past window is created dead-on-arrival (every buy reverts 'TSP: token sale is over'). The builders refuse past end-times before any transaction.109- ⚠ Native BNB in sale tiers uses the sentinel address 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE, NOT the zero address (0x0 reverts 'TSP: incorrect token'). A native-currency buy must send msg.value equal to the buy amount. The dexe_otc_* composites canonicalize this.110- ⚠ Tier exchange rates are scaled ×1e25 (PRECISION) on-chain. Pass human units to the dexe_otc_* composites and they scale for you; only ADVANCED raw structs need pre-scaled values. A hand-scaled rate off by 10^2 sells the whole allocation for pennies.111- ℹ Whitelisted tiers use a merkle root; the tier's uri must point to IPFS JSON {"list":[lowercased addresses]} so buyers can regenerate proofs — dexe_otc_dao_open_sale auto-uploads it when uri is empty (needs DEXE_PINATA_JWT). Buyer-side reads need the proof BEFORE getUserViews or canParticipate reads false.112- ℹ Amount strings: digits-only = RAW smallest units (wei); a decimal point ("12.5") = human units scaled by the token's REAL on-chain decimals (never assumed 18). Durations and delays are SECONDS (86400 = 1 day). Composite quorum/percent params are plain percent numbers (51).113114_For the machine-readable plan (interview questions with risk notes, step templates with `flowContext` chaining), call the `dexe_guide` tool with `flow:"otc_sale"`._115<!-- END GENERATED: flow-recipe -->