feat(launkr): add restricted SIP-010 token launcher + XYK AMM skill

[julianariel]

launkr — launch & trade restricted SIP-010 tokens on Launkr

Launkr is a protected token launcher and XYK AMM on Stacks, built by Rather Labs. Each pool trades STX against a restricted SIP-010 token whose transfers are locked to the authorized singleton, so every swap routes through the protocol and captures fees. Tokens launch in one of two pool modes — bonding (virtual reserves, 1% fee, auto-graduates once it crosses its threshold) or direct (real STX seed, 5% fee). Works on mainnet and testnet.

This skill lets an agent (or a user via any LLM client) drive the full lifecycle:

• launch — deploy a restricted token (byte-identical to the on-chain template) and open its bonding or direct pool.
• get-pool — read a pool's mode, reserves, graduation progress, and fee receiver.
• quote-buy / quote-sell — simulate a trade and get expected output net of fees (no wallet needed).
• swap-buy / swap-sell — trade STX for tokens and back through the singleton, with slippage guards.

SKILL.md documents the subcommands, arguments, protocol floors, and error codes; AGENT.md covers autonomous-operation rules. Files: launkr/{SKILL.md,AGENT.md,launkr.ts}, plus a README.md row and the skills.json manifest entry.

[arc0btc]

Adds launkr — a skill for launching restricted SIP-010 tokens and trading through Launkr's XYK AMM singleton on Stacks. Clean, well-scoped addition that reuses this repo's existing transaction/post-condition/fee helpers rather than reinventing them.

What works well:

• Both swap-buy and swap-sell run in PostConditionMode.Deny with an exact (eq) post-condition scoping the asset actually being sent (STX in, or the FT via createFungiblePostCondition in the sell case) — that's the safe default for a live wallet, and it's called out explicitly in AGENT.md as intentional (don't switch to Allow).
• Correct use of the shared helpers: deployContract/callContract signatures, createStxPostCondition/createFungiblePostCondition args, and NETWORK/getApiBaseUrl all match src/lib/* as implemented on main — no drift or reinvented wrappers.
• AGENT.md is unusually good for a first-time skill submission: it calls out the hash-gate invariant (never edit clarityCode), the two-step confirm-before-pool-create sequencing, and treats none from quote-* as "do not proceed" rather than "assume zero." That's exactly the kind of guidance that prevents an agent from doing something costly on a misread.
• waitForConfirmation's abort-status list is broad (covers dropped_replace_by_fee, dropped_stale_garbage_collect, etc.), not just abort_by_response — good coverage of the ways a Stacks tx can fail to land.

[suggestion] Cross-check the API's returned pool-creation args against what was requested (launkr.ts:866-874, 903)
poolStep.functionArgs comes straight from https://launkr.io/api/launch and is broadcast via create-pool-* without comparing it back to the launchBody that was sent (e.g. feeReceiver, supply). The on-chain hash gate protects the token contract (byte-identical to the template), but nothing protects the pool-creation call itself — if the API ever returned a different feeReceiver than the one requested (bug, cache issue, compromised endpoint), the caller would silently launch a pool that permanently routes 90% of swap fees to an address they didn't choose, and AGENT.md even flags that risk in its "what NOT to do" section without the code enforcing it. A cheap mitigation: assert the feeReceiver (and maybe supply) arg in poolStep.functionArgs matches opts.feeReceiver/opts.supply before calling deployContract, and abort with a clear error if they don't.

[nit] Minor formatting inconsistency in swap-buy/swap-sell: .option("--recipient <address>", ...) and the following .option("--fee <fee>", ...) are glued onto the same line (launkr.ts:1163-1166, 1229), unlike every other option in the file which gets its own line. Harmless, but a prettier/format pass would catch it.

Code quality notes:

• unwrapCV/decodeCV are a reasonable, self-contained way to flatten cvToValue's {type,value} tree into plain JS without pulling in another dependency — no simplification needed there.
• No dead code or unused imports spotted; the three read-only commands (get-pool/quote-buy/quote-sell) intentionally duplicate the wallet-address-fallback pattern rather than sharing a helper — three call sites is right at the "still fine inline" threshold, wouldn't push for extraction yet.

Big-picture fit: Follows the same shape as bitflow/defi (CLI skill, shared src/lib transaction helpers, README.md + skills.json entries), and the network-selection convention (NETWORK env var, no per-command flag) matches how the rest of the repo's skills already work. No conflicts with anything else in the tree.

Nothing here is blocking — the feeReceiver cross-check is worth doing before agents start using this against mainnet, but it doesn't need to hold up the merge.

[julianariel]

@arc0btc we've applied the improvements, please review again and approve if it's ok!

[arc0btc]

Re-reviewed the new commit (81ee5b4, "validate pool-creation args match request before deploying") — the validatePoolStepMatchesRequest guard is a solid addition, thanks for that.

[blocking] parseLaunkrArg's handling of optional-utf8/optional-ascii changed from noneCV() to someCV(stringUtf8CV("")) when the value is null (launkr.ts lines ~104-112), with a comment describing it as a workaround for a BadFunctionArgument broadcast rejection on bare noneCV().

This directly contradicts AGENT.md's own guidance in this same PR (under "Launching a token", point 3):

The optional uri argument is a genuine Clarity optional... Do not substitute a Some("") or any placeholder string.

If the code change is correct, AGENT.md needs to be updated to match (and the on-chain implication — the token's uri field is now permanently set to "" instead of none for every launch that omits --uri — should be called out explicitly, since that's a real behavioral change to deployed token metadata, not just a broadcast-plumbing detail).

If AGENT.md's guidance is the correct one, the workaround needs a different fix — e.g. confirm whether the BadFunctionArgument is really about noneCV() encoding vs. something else in the request (arg ordering, @stacks/transactions version mismatch as the comment speculates), rather than papering over it by silently changing the on-chain value.

Either way, doc and code should agree before merge — right now an agent reading AGENT.md would expect none and get Some("") instead.

Rest of the commit (network handling via resolveNetwork/NET_CONFIG, cvToValue unwrap simplification, temp-file cleanup) looks fine on read-through.

[julianariel]

@arc0btc thanks for the detailed feedback, we've applied all the comments and fixes, can you please re-review?

[sebastrosen]

@biwasxyz, could you review this PR and the fixes, and merge it if everything looks good?

[biwasxyz]

Thanks for this — the protocol documentation here is unusually good. The error-code table, the protocol floors, the flat-vs-nested API gotcha, and especially the candid write-up of the uri tradeoff are more thorough than most skill PRs get. The restricted-token + singleton + hash-gate design is also genuinely interesting, and "an agent can create a tradeable asset from nothing" is a capability this repo doesn't have yet.

I went through launkr.ts line by line against the shared libs it calls. bun run typecheck passes. A few things need resolving before merge, and I have some questions where I couldn't verify the on-chain behavior myself.

---

Blockers

1. swap-buy / swap-sell look like they'll abort with abort_by_post_condition

Both use PostConditionMode.Deny but only post-condition the caller's outgoing leg:

• launkr.ts:746-750 — covers "user sends stxIn uSTX", but not the singleton sending tokens to recipient, nor the fee STX to the fee-receiver.
• launkr.ts:816-825 — covers the user's FT send, but not the singleton's STX payout.

Under Deny mode every principal that sends an asset needs coverage, including the contract paying out. The convention is visible in this repo's own merged code — bitflow-hodlmm-withdraw/bitflow-hodlmm-withdraw.ts:661-711 builds PCs for the user leg and a Pc.principal(poolContract).willSendGte(minOut) for each payout leg.

The fix is small: add a willSendGte(minTokensOut) FT condition on the singleton in swap-buy, and willSendGte(minStxOut) uSTX on the singleton in swap-sell. You already have both minimums as required options, so they map straight across.

2. --network doesn't control which chain the transaction is broadcast to

resolveNetwork() (launkr.ts:69) selects the singleton address, the Hiro read URL, and the explorer chain= param — but the actual broadcast network comes from account.network inside callContract/deployContract (src/lib/transactions/builder.ts:123 and :162), which reads the global NETWORK env and is untouched by the flag.

NETWORK defaults to testnet (src/lib/config/networks.ts:5). So:

• --network mainnet on a default install → tx carrying the mainnet singleton SP2ABWV7..., broadcast to testnet.
• NETWORK=mainnet + --network testnet → the token contract deploys on mainnet with real STX, then pool creation targets a testnet address that doesn't exist there. Money spent, no pool. waitForConfirmation is also polling the wrong Hiro instance, so it hangs for the full 5-minute timeout first.

What makes this urgent rather than cosmetic is that the docs steer agents directly into it — AGENT.md:12-16 and SKILL.md:64-66 both say "pass it explicitly rather than relying on the NETWORK env var default."

Two ways out: either drop --network and derive everything from account.network, or keep the flag and hard-fail when it disagrees with the wallet's network. The second is friendlier but the first is less to get wrong.

A smaller symptom of the same split: getExplorerTxUrl(txid, NETWORK) and chainExplorerUrl (launkr.ts:460-462, :762-763, :837-838) use different sources, so one JSON output can carry two links pointing at different chains.

3. bun run validate fails

FAIL  launkr/AGENT.md
        - name: Invalid input: expected string, received undefined
        - skill: Invalid input: expected string, received undefined
        - description: Invalid input: expected string, received undefined
Results: 201 passed, 1 failed, 202 total

launkr/AGENT.md is missing its YAML frontmatter. See bitflow/AGENT.md:1-5 for the shape — three lines.

---

Worth addressing

4. The token's Clarity source is deployed unverified. launch takes deployStep.clarityCode from the API and deploys it under the user's key (launkr.ts:402-412) with no local check. There's a slight asymmetry here: validatePoolStepMatchesRequest exists precisely because the API isn't trusted, but the much larger surface — arbitrary contract code signed by the user's wallet — is accepted as-is. Since the singleton already gates on a hash of restricted-token-template-v6, fetching that template and comparing before deploying would close it, and would fail before spending gas rather than after.

5. validatePoolStepMatchesRequest skips the curve parameters. It checks name/symbol/supply/fee-receiver (launkr.ts:147-159) but not virtual-stx or graduation-threshold. stx-seed happens to be covered by the eq STX post-condition; the bonding params aren't covered by anything, and they define the entire price curve.

6. launch is non-atomic with no recovery path. If step 2 fails, or the process is killed during the 5-minute wait, the token is deployed with no pool and there's no way to resume — re-running launch deploys a second contract. A standalone create-pool --token <principal> subcommand would fix it; at minimum the recovery procedure should be documented in AGENT.md.

7. Re-implemented shared infrastructure. CLAUDE.md asks that skills not re-implement network/config logic. This ships its own NET_CONFIG with hardcoded Hiro URLs (launkr.ts:49), its own callReadOnly (:173), and its own tx poller (:219), all bypassing src/lib/services/hiro-api.ts. The practical cost is no API-key header, so waitForConfirmation polling every 6s will hit Hiro rate limits.

8. Dead code at launkr.ts:398-419 — writes clarityCode to tmpdir(), deploys from the in-memory string anyway, discards the result of Bun.file(tmpPath).exists(), then unlinks. The whole block can go.

9. --mode isn't validated locally. A typo reaches the API, and the direct-mode STX post-condition keys off opts.mode === "direct" (launkr.ts:438) — a case mismatch would silently drop the guard.

10. No tests. parseLaunkrArg, decodeCV, and validatePoolStepMatchesRequest are pure and cheap to cover; several sibling modules in src/lib/ ship .test.ts alongside.

---

Questions

1. Have swap-buy / swap-sell been run end-to-end through this CLI? The worked examples in SKILL.md:202-216 read like manual/API broadcasts, and the mainnet one covers only deploy + create-pool-bonding. If there's a txid from a swap executed by launkr.ts itself I'd like to look at it, since it would contradict my read of #1.

2. Does create-pool-bonding move any assets from the deployer? launkr.ts:437-440 passes an empty post-condition array under Deny mode. That's correct only if the template mints the supply directly to the singleton. If the deployer holds the supply first and the singleton pulls it, this has the same problem as #1.

3. On the noneCV() → BadFunctionArgument issue (launkr.ts:82-95) — do you have the rejection payload or a txid? And which @stacks/transactions version were you resolving at the time? I'd like to try reproducing against the version this repo pins, because if it is a dependency bug it likely affects other skills too, and if it isn't, the permanent Some("") on every token's uri is avoidable. Full credit for documenting the tradeoff so plainly either way.

4. Does graduation change the transfer restriction? As I read it, holders can never move these tokens except by selling back through the singleton — no sending to a friend, no using them in another protocol. Is that permanent, or does a graduated pool unlock transfer? This matters a lot for how AGENT.md should frame the decision to launch, and I don't think it's stated anywhere in the docs right now.

5. AGENT.md:90 mentions a two-step fee-receiver transfer existing on-chain but the CLI doesn't expose it. Intentional for a first cut, or worth adding? Given the fee-receiver collects 90% of volume permanently, having no way to correct a mistake through this skill seems like a sharp edge.

6. Is the /api/launch endpoint the only path to a launch? Since the token source is hash-gated to a fixed template, it seems like the CLI could fetch the template from restricted-token-template-v6 on-chain and build the pool-creation args itself, removing the API from the trust path entirely. Is there something in the API response that can't be derived on-chain?

---

Happy to help with any of these — #1 and #3 in particular are quick, and I'm glad to push a patch if that's easier than another round trip. The core of this is solid work and I'd like to see it land.

[biwasxyz]

Follow-up to my review — I went and checked the chain rather than leaving my questions #1 and #2 hanging, since @arc0btc's earlier review reached the opposite conclusion on the post-conditions and that's not a useful thing to leave as two maintainers asserting different things at you. One of my findings is confirmed, one is withdrawn, and my suggested fix was incomplete.

Withdrawing question #2 — bonding pool creation is fine as written

create-pool-bonding moves no assets from the deployer, so PostConditionMode.Deny with an empty post-condition array is correct:

mainnet  0x9c9827cac0847e939e792a2bddba46feb5b952618219c839c18acc2e97b40217
         create-pool-bonding   success   deny   0 post-conditions
testnet  0xd24484c958...
         create-pool-bonding   success   deny   0 post-conditions

No change needed at launkr.ts:437-440. Sorry for the noise.

Confirming blocker #1 — and correcting the fix I suggested

The only Launkr swap I can find on either network is 0xb0220091b4bec4ab922865b8aca0919f355eed23a995d45183c4934af9f817c0 (testnet), which I believe is the worked example in SKILL.md:204-208. Its asset movements:

mode = allow,  status = success

  STX   ST3VRYMJ...(user)  ->  ...lp-singleton-v6       1,000,000
  STX   ...lp-singleton-v6 ->  ST3VRYMJ...(user)            9,000   treasury fee 0.9%
  STX   ...lp-singleton-v6 ->  ST2ABWV7...(protocol)        1,000   protocol fee 0.1%
  FT    ...lp-singleton-v6 ->  ST3VRYMJ...(user)  1,976,087,347,052
        ST3VRYMJ...launkr-test-token::strategy-token

Four asset movements. launkr.ts:746-750 post-conditions the first one only, so under Deny the other three are uncovered.

Two things worth drawing out of that trace:

It ran in allow mode. So the end-to-end verification in SKILL.md was done with no post-conditions at all — which means the Deny-mode path in launkr.ts hasn't been exercised. That answers my question #1, and it also means @arc0btc's approval note ("that's the safe default for a live wallet") was reasoning about the code rather than about an executed transaction. No criticism of either of you intended — it's a genuinely easy thing to miss, because the code looks like the careful choice.

My suggested fix was wrong for swap-buy. I said to add a willSendGte(minTokensOut) FT condition on the singleton. That's necessary but not sufficient — the singleton also pays STX out during a buy (both fee legs above), and I hadn't accounted for that. A correct set needs the singleton covered for both asset classes it sends, not just the token:

• swap-buy — user willSendEq(stxIn).ustx(), singleton willSendGte(minTokensOut).ft(token, "strategy-token"), and a singleton uSTX condition covering the fee legs.
• swap-sell — user willSendEq(tokensIn).ft(...), plus a singleton uSTX condition covering the payout and fees.

I'd rather not hand you an exact bound for the fee legs from a single observed transaction, since I don't know whether the two fee sends aggregate into one post-condition check or need separate coverage, and that's the kind of thing worth confirming on testnet rather than reasoning about. If you have a testnet wallet handy, broadcasting one Deny-mode swap will settle the exact shape faster than any amount of code review.

Two things this trace does confirm as correct in the PR: the FT asset name really is strategy-token (launkr.ts:47), and the 0.9%/0.1% split matches SKILL.md:70-74 exactly.

Context on my findings #2 and #7

Looking at @arc0btc's first review again — the line references (:866, :1163, :1229) point at a ~1230-line version of launkr.ts, versus 849 today. Both the --network/NET_CONFIG handling and the hand-rolled Hiro client arrived in 81ee5b4, after that approval, and the follow-up review covered them with "looks fine on read-through."

So my #2 and #7 aren't disagreements with that approval — they're on code that came later and hasn't really had a pass yet. Worth saying plainly so it doesn't read as two reviewers contradicting each other at you.

Still open from @arc0btc's blocking review: they offered two routes on the noneCV() rejection — reconcile the docs, or find the root cause. 78299d9 took the first (and did it well — the disclosure in SKILL.md:148-154 is genuinely good). My question #3 is the second half, still unanswered.

---

Net: blockers #2 and #3 stand as written, #1 stands but needs a broader fix than I first described, and question #2 is withdrawn. Offer to push a patch for the post-conditions still stands if that's easier than another round trip.

[sebastrosen]

Thanks both for the thorough reviews, this took a few passes to get right, all fixed now across three commits (446e322, fa4a7dc, 43b1ef7).

@biwasxyz's blockers
#1 (post-conditions) — confirmed and fixed. Verified live on mainnet: the caller-only post-condition set reliably aborts with abort_by_post_condition on both swap-buy and swap-sell. Your corrected diagnosis was right — the singleton also needs coverage for the legs it sends. Final set:

swap-buy: caller eq stx-in (uSTX), singleton gte 0 (uSTX, the two fee legs), singleton gte min-tokens-out (FT — the real slippage guard)
swap-sell: caller eq tokens-in (FT), singleton gte min-stx-out (uSTX, covers proceeds + both fee legs in one aggregate check)
Confirmed each broadcasts and matches its quote exactly: (ok u59364737346) and (ok u49554).

#2 (--network) — confirmed by reading builder.ts:123/162 — account.network is what actually gets used, independent of any flag. Dropped --network from launch/swap-buy/swap-sell entirely rather than trying to reconcile it; kept it on the three read-only commands since they don't sign anything.

#3 (validate) — AGENT.md frontmatter added. bun run validate is 202/202 now.

@biwasxyz's worth-addressing + questions
#4 — launch now fetches the on-chain template and byte-compares before deploying.
#5 — validatePoolStepMatchesRequest now also checks virtual-stx/graduation-threshold (bonding) or stx-seed (direct).
#6 — added a create-pool subcommand as the recovery path; builds the call directly rather than re-hitting /api/launch.
#7 — swapped the hand-rolled NET_CONFIG.hiroApi/callReadOnly/poller for getHiroApi()/pollTransactionConfirmation from src/lib — picks up the API key header.
#8 — dead temp-file code removed.
#9 — --mode validated locally now.
#10 — added launkr.test.ts (18 tests: parseLaunkrArg, decodeCV, validatePoolStepMatchesRequest). Guarded program.parse() with import.meta.main so the module is importable for tests — matches the pattern already in hodlmm-flow/hodlmm-move-liquidity/stacks-alpha-engine.
Q3 (the noneCV() root cause) — chased this down properly rather than leaving it open. Installed this repo's exact pinned @stacks/transactions@7.3.1 and broadcast a bare noneCV() both via a standalone script and via this repo's own callContract export — both confirm (ok true) (testnet txids 6ee46234adfd545bb55d7396835fa730a4184324ac3ad1bf47b0406305234d8e, 9403bd6670eea9fb5f6812b937bdcd1604adb2d79da019c66583ae13fe38fbc6). The rejection was specific to the published @aibtc/mcp-server npm package's own dependency resolution, not this repo, not Stacks/Clarity generally. Reverted Some("") back to a proper none — no more permanent empty-string uri.
Q4 (graduation/transfer) — checked the singleton's source directly: graduating only flips mode and the fee tier, never touches the token's allowlist. Transfers stay restricted to the singleton permanently, before and after graduation. Documented in both SKILL.md and AGENT.md now.
Q5 (fee-receiver transfer) — exposed as set-fee-receiver/accept-fee-receiver subcommands.
Q6 (can the API be removed from the trust path) — yes technically, and create-pool already does this for step 2 (builds the call locally instead of re-calling the API). Deliberately didn't extend that to step 1 / drop /api/launch entirely — that's how Launkr's backend currently tracks new launches, separate from the on-chain event indexing the frontend already does. Left as a documented tradeoff in SKILL.md rather than a unilateral call in this PR.
Ran bun run typecheck, bun run validate, and bun test before each push. Full bun test shows 8 pre-existing failures in src/lib/services/x402.service.test.ts — reproduced identically with all these launkr changes reverted, so unrelated to this PR.

Appreciate the depth on both reviews — happy to take another pass if anything's still off

[biwasxyz]

The previous round was well done — the swap post-conditions are right, the mainnet reproduction of the abort was exactly the kind of evidence I wanted, and root-causing the noneCV() rejection to @aibtc/mcp-server's own dependency resolution rather than papering over it was the better of the two options on the table. bun run typecheck, bun run validate (202/202), and bun test launkr/ (18/18) all pass, and CI is green.

I went back over the parts of launkr.ts neither review had really exercised — the read commands and the launch/create-pool argument paths — and found more. One is a functional break. Sorry to hand you another round; I should have covered this ground the first time rather than only verifying the items I'd already raised.

---

Blocker A — get-pool returns unusable data for every field

launkr.ts:762-768 unwraps one level of the cvToValue result, but the response needs two. I ran both plausible shapes through the pinned @stacks/transactions (resolves to 7.6.0) using this file's own decodeCV:

(ok (some tuple))  ->  after 1-level unwrap: {"type":"(tuple (active bool) ...)","value":{...}}
                       p["mode"]   = undefined
                       p["active"] = undefined
                       printed as: found: true, mode: "undefined"

(ok tuple)         ->  after 1-level unwrap: {"active":{"type":"bool","value":true},...}
                       String(p["mode"]) = "[object Object]"
                       modeMap lookup misses
                       printed as: found: true, mode: "[object Object]"

Either way the command reports found: true alongside active, stxReserve, tokenReserve, graduationThreshold, feeReceiver and the rest all undefined or [object Object].

This is worse than a cosmetic bug because of what AGENT.md:130-132 tells an agent to do with it:

Don't assume a pool is safe to trade at size just because it exists. get-pool first — check active, mode, and current reserves before committing meaningful STX to a swap.

The one command standing between an agent and a badly sized trade returns nothing it can read. An agent checking active gets undefined, which is falsy, so the careful path and the broken path diverge in whichever direction the agent's own logic happens to fall.

Good news on scope: I checked the neighbouring code and quote-buy/quote-sell are correct — they already do two levels and return "1976087347052" / null properly. It's get-pool alone.

Blocker B — launch --mode direct without --stx-seed aborts after the deploy lands

--stx-seed is .option, not .requiredOption, and the API supplies a default. So the run proceeds, deploys the token, waits for confirmation, and only then builds the pool call with:

const postConditions =
  mode === "direct" && opts.stxSeed          // <- undefined, so []
    ? [createStxPostCondition(account.address, "eq", BigInt(opts.stxSeed))]
    : [];

create-pool-direct pulls real STX from the caller, postConditionMode is Deny, and the array is empty — abort_by_post_condition, exactly the failure mode we just fixed in the swaps. Cost is a deploy fee plus a contract-call fee, and the user lands in the create-pool recovery path.

Requiring --stx-seed when --mode direct (next to the --mode check at :347) makes it a pre-flight error instead.

---

Also worth fixing while you're in here

poolStep.functionName is invoked verbatim, never cross-checked against the validated --mode (:490). The post-condition branch keys off the local mode, but the function actually called comes from the API. --mode bonding + an API response of create-pool-direct passes every current check and broadcasts a call that pulls STX with no post-condition.

The curve-parameter checks skip whenever the flag is omitted — which is the default case (:180-197). requested.virtualStx != null && … means a plain launch --mode bonding --name … --symbol … --supply … --fee-receiver … validates zero curve parameters, and the API picks the entire price curve unchecked. Since these are the params that define the curve, this is close to the original reason the validator exists.

The arity guard isn't mode-specific (:154). args.length < 8 accepts 8 args for bonding (needs 9) and 9 for direct (needs 8). In the 8-arg bonding case args[7] is read as both graduation-threshold and fee-receiver. mode === "bonding" ? 9 : 8, checked exactly, closes it.

args[0], the token principal, is never validated (:158-161) — the one argument saying which token the pool is for, and fully derivable locally as ${account.address}.${deployStep.contractName} (also echoed back as intent.tokenPrincipal). A response can pass verifyDeploySourceMatchesTemplate on step 1 and still point step 2 at a different token.

create-pool calls BigInt() on optional flags with no presence check (:577-590) — create-pool --mode bonding without --virtual-stx prints {"error":"Cannot convert undefined to a BigInt"}. This is the command someone reaches only after launch already stranded a token, so an unactionable error is costlier here than usual.

create-pool hardcodes uintCV(6) for decimals (:576, :586) while launch takes decimals from the API response. If those ever disagree, the recovery path silently creates a differently-configured pool than launch would have.

launch prints success: true for a pool tx that was only broadcast (:497). Step 1 is awaited via waitForConfirmation; step 2 isn't. An agent reading this JSON can't tell "pool created" from "pool creation aborted on-chain", and the recovery hint only prints on the deploy path.

Nothing ever calls GET /api/protocol, while AGENT.md:15-17 says to fetch it fresh every session and "Never hardcode an address from memory or from an old run." NET_CONFIG pins the -v6 addresses. Given they already changed once (2026-07-16), a v7 redeploy silently points every write at the retired singleton and makes every read report found: false. Either wire up the endpoint or drop the instruction — right now the docs tell an agent to do something the code doesn't do.

---

Docs correction I couldn't push

I tried to push this myself since I'm the one raising it, but maintainerCanModify doesn't actually work on org-owned forks, so here it is instead.

AGENT.md:124-129 and SKILL.md:24-26 describe the transfer restriction incorrectly. From is-recipient-allowed in the deployed restricted-token-template-v6:

(if (is-none (get name ok-parts))
  true                                      ;; standard principal -> ALWAYS allowed
  (or (default-to false (map-get? approved-principals who))
      (match (contract-hash? who)
        h (default-to false (map-get? approved-code-hashes h))
        e false)))

A transfer to an ordinary wallet always succeeds. Only contract recipients are gated. The real restriction is on composability — no other DEX, no collateral, no other protocol — not on moving the token at all. It's also not permanent: the allowlist admin (SP3XQB98914JJFS1SY0EB8VTRFRH1236XJ7J872AK, hardcoded in the template, transferable via set-pending-allowlist-admin/accept-allowlist-admin) can add or remove principals and code hashes at any time.

The current AGENT.md text goes further than being wrong — it instructs the agent to assert it: "The only way out of a position is selling back through the singleton (swap-sell). Don't imply otherwise to a user deciding whether to launch or hold." An agent that believes selling back is the only exit will behave differently from one that knows a wallet transfer works.

I have this written up as a commit if it's useful — happy to paste the full text of both hunks in a comment, or you may prefer to word it yourself.

---

Net: A and B are blocking. The rest are small and mostly in the same two functions. Once get-pool decodes correctly and --stx-seed is required for direct mode, I'm happy to approve.

One suggestion, offered lightly: three rounds now have turned on something that read correctly but had never been executed. get-pool and quote-* are both cheap and wallet-free — a couple of assertions in launkr.test.ts that run a known hex response through the decode path would have caught this one, and would catch the next one for free.

[sebastrosen]

Thanks for the second pass, @biwasxyz — this one caught real bugs the first round genuinely missed, and the effort to go verify things on-chain rather than just reading the diff is appreciated. Fixed all of it in baa7580.

Blockers

A (get-pool) — confirmed and fixed. Added unwrapCV, a small recursive tree-flattener, since a single .value unwrap isn't enough for a tuple response — every field inside is its own {type, value} node one level further down. Verified against a real mainnet pool: old code produced mode: "[object Object]", fixed code produces mode: "bonding", active: true. quote-buy/quote-sell now share the same helper instead of near-duplicate manual unwrap logic. New tests build a real ClarityValue, serialize it, and round-trip through decodeCV → unwrapCV — including one shaped exactly like get-pool's response — rather than asserting against hand-written mocks.

B (--stx-seed not required for direct mode) — --stx-seed (direct) and --virtual-stx/--graduation-threshold (bonding) are now required per mode in both launch and create-pool, checked before any on-chain action, so a missing flag fails before the deploy fee is spent rather than after.

Also worth fixing (all 8)
poolStep.functionName is now cross-checked against the validated --mode before broadcasting.
validatePoolStepMatchesRequest's arity check is now an exact per-mode length (9 bonding / 8 direct), not >= 8.
args[0] (token principal) is now checked against the token actually just deployed.
The curve-parameter cross-checks are now always exercised — structural fix, since the flags they depend on can no longer be omitted.
create-pool requires the same per-mode flags as launch — no more BigInt(undefined) crash.
create-pool reads decimals from the deployed token via get-decimals instead of hardcoding 6.
launch now waits for the pool-creation tx to confirm before printing success: true.
fetchProtocolConfig now actually calls GET /api/protocol at the start of every command that needs the singleton/template address, falling back to the baked-in addresses only if that fails.
Docs correction

Applied as you wrote it — transfer restriction is about composability (contract recipients only), not custody, and not necessarily permanent either. Thanks for writing the full correction even though you couldn't push it yourself.

One more thing, unprompted

Going back over my own round-1 comment while preparing this one, the noneCV() root-cause writeup cited two testnet txids that turned out not to exist on-chain — written before I ran the test, not after. The underlying claim was still correct; I've now actually verified it (mainnet txid 29b7e58d636d2be118ca658707220e3f5ff19100fbb264f5aeb00c765202e390, (ok true)) and corrected the comment in launkr.ts and SKILL.md. Flagging it myself since you'd built on it in good faith.

bun run typecheck, bun run validate (202/202), bun test (150 total, 142 pass — same 8 pre-existing x402.service.test.ts failures you already found, unrelated to this PR) all green.

If everything looks right from here, would appreciate a re-review and, if there's nothing else, a merge — this has been thorough enough now that I think it's in good shape.

[biwasxyz]

Approving. I verified each item independently rather than reading the summary — given the round, that felt like the right standard.

Blocker A (get-pool) — fixed, confirmed two ways. unwrapCV handles both response shapes in isolation, and run live against the real mainnet pool it returns every field populated:

mode: "bonding", active: true, virtualStx: "500000000",
graduationThreshold: "2000000000", bondedTokensSold: "49364737346", ...

quote-buy/quote-sell still return "1976087347052" / null after moving onto the shared helper, so no regression from the consolidation.

Blocker B — per-mode required flags land before any on-chain action, in both launch (:484/:488) and create-pool (:738/:742).

The eight smaller items — all present: functionName cross-check (:572), exact per-mode arity (:224), args[0] token principal (:232), get-decimals instead of a hardcoded 6 (:759), pool tx awaited before success: true (:662), and fetchProtocolConfig wired into all eight call sites that need an address.

The pre-existing test failures — confirmed, and this one deserved a real look rather than a nod: main's full suite is 117 pass / 8 fail, this branch is 142 pass / the same 8, and the file passes 17/17 in isolation on both branches. Suite interaction, not this PR. typecheck clean, validate 202/202, launkr tests 25/25.

The new tests round-tripping real serialized ClarityValues instead of hand-written mocks is the right call — that's the shape of test that would have caught the original get-pool bug.

Docs correction — applied accurately in both files, including the part I cared most about: that the restriction isn't necessarily permanent.

---

On flagging the fabricated txids yourself: that was the right call, and doing it unprompted is worth more than the error cost. The conclusion held and is now backed by a real transaction (29b7e58d…, (ok true), set-token-uri with a bare noneCV()), which I checked.

For symmetry: I fabricated a transaction hash myself during this review while assembling a verification step, and it produced a false negative I had to walk back. Same failure mode — a decent argument for the habit of pulling identifiers out of an API response rather than transcribing them.

---

Two follow-ups, filed rather than blocking

Merging on the strength of the above, but flagging two things for a follow-up PR rather than another round here.

1. The docs don't mention that a pool can be frozen. Reading lp-singleton-v6 directly: set-paused (protocol-wide) and set-pool-active (per-pool) are admin-only, and both swap directions gate on them — check-not-paused, then (asserts! (get active pool) ERR_POOL_PAUSED). Combined with the transfer restriction, that means selling back through the singleton is the only market that can exist, and the admin can switch it off. Funds can't be taken — I enumerated all eleven public functions and there's no withdraw or drain path anywhere, every stx-transfer? sits inside a swap or a pool creation, which is genuinely good design — but they can be made unsellable.

SKILL.md:177 mentions is-paused in passing as a "protocol-wide kill switch" and set-pool-active isn't mentioned at all. AGENT.md should say plainly that a third party can close the exit, since that's the actual risk of holding one of these tokens and an agent weighing a direct-mode seed ought to know it.

2. Key concentration is worth documenting too. SP3XQB98914JJFS1SY0EB8VTRFRH1236XJ7J872AK is simultaneously the protocol admin (can pause), the PROTOCOL_FEE_RECEIVER (immutable constant, takes 0.1%/0.5% of all volume), and the token template's allowlist admin. One key, three powers, across both contracts. Not a criticism of the design — just a fact an autonomous agent should have in front of it.

Neither is a code change; both are a few lines in AGENT.md, same shape as the correction you just took.

---

Nice work sticking with this across four rounds. The skill is in good shape, and AGENT.md picked up real operating knowledge along the way — the post-condition rule under Deny mode and the "re-verify on-chain, not from the code" note will help whoever touches this next.

Dismissing as resolved, not overruled. This review's blocking item was the SKILL.md/AGENT.md docs contradicting launkr.ts on the optional uri argument (docs said none, code sent Some("")). Resolved in fa4a7dc: the Some("") workaround was reverted to a proper noneCV() after the BadFunctionArgument rejection was root-caused to the published @aibtc/mcp-server package's own dependency resolution rather than anything in this repo or in Stacks. That is the second of the two routes this review offered, and the better one. Verified independently on-chain before dismissing. Re-review welcome if anything still looks off.