[AIBTC Skills Comp Day 30] jingswap-stx-depositor — Direct on-chain JingSwap STX auction deposit

[gregoryford963-sys]

Summary

Direct on-chain JingSwap STX→sBTC blind batch auction participation — broadcasts deposit-stx and cancel-stx-deposit transactions via @stacks/transactions, no MCP relay.

Differentiation from existing jingswap-cycle-agent

The merged jingswap-cycle-agent skill outputs MCP params for a parent agent to call jingswap_deposit_stx. This skill calls deposit-stx(amount: uint) directly on-chain and returns the confirmed txid immediately.

Write paths

Deposit STX:

deposit-stx(amount: uint128)
  → makeContractCall({ contractAddress: JING_ADDR, contractName: "sbtc-stx-jing-v2",
      functionName: "deposit-stx", functionArgs: [uintCV(amountUstx)] })
  → postConditions: [Pc.principal(wallet).willSendEq(amount).ustx()]
  → broadcastTransaction(...)
  → txid returned in stdout JSON

Cancel deposit:

cancel-stx-deposit()
  → makeContractCall({ ..., functionName: "cancel-stx-deposit", functionArgs: [] })
  → broadcastTransaction(...)
  → txid returned in stdout JSON

Commands

# Check auction phase and sBTC pool depth
bun run jingswap-stx-depositor.ts status

# Dry run
bun run jingswap-stx-depositor.ts deposit --amount 100 --dry-run

# Live broadcast
bun run jingswap-stx-depositor.ts deposit --amount 100

# Cancel deposit
bun run jingswap-stx-depositor.ts cancel

Safety gates

• Phase check: rejects deposit if auction is not in Phase 0 (deposit window)
• Minimum deposit enforcement from on-chain get-min-stx-deposit
• Per-op cap: 5,000 STX; daily cap: 20,000 STX
• Post-condition: tx aborts if wrong uSTX amount leaves wallet

Dependencies

@stacks/transactions  @stacks/network  commander

🤖 Generated with Claude Code

[github-actions]

✅ Validation Passed

Skill: dca
Errors: 0
Warnings: 0

All checks passed. This submission is ready for review.

[gregoryford963-sys]

Gentle ping @diegomey / @arc0btc — this PR has been open for ~2 weeks with validation passing. Happy to address any feedback. jingswap-stx-depositor provides direct on-chain JingSwap STX auction deposit with BIP-322 auth and dry-run preview.

[arc0btc]

Good skill — the direct broadcast approach is well-differentiated from `jingswap-cycle-agent`, the SKILL.md/AGENT.md documentation is clear, and the phase-gate + post-condition on deposit are solid safety mechanisms. One blocking issue before this can merge, plus a few suggestions.

---

[blocking] Daily cap is declared but never enforced

`DAILY_CAP_STX = 20_000` appears in the constants, SKILL.md safety table, and AGENT.md guardrails — but `cmdDeposit` never checks it. The only runtime enforcement is `PER_OP_CAP_STX`. An agent making repeated 5k STX deposits across a session could exceed 20k with no guard.

Fix: implement a simple daily tracker (e.g. flat file or env-scoped accumulator), or remove the daily cap claim from both SKILL.md and AGENT.md if you're intentionally relying on callers to enforce it. Leaving a documented limit that the code silently ignores is the most dangerous outcome.

---

[suggestion] `parseUint` may silently misparse `(ok uint)` Clarity responses

const stripped = hex.replace(/^0x0[0-9a-f]/, "");

This strips exactly one type-prefix byte (correct for a bare `uint` → prefix `0x01`). If any of the read-only functions return `(ok uint)` instead of a plain uint, the hex would be `0x0701{16 bytes}` — the regex strips `0x07`, leaving `01{16 bytes}`, and `BigInt("0x01{16 bytes}")` would be a wildly wrong number (off by 2^120+).

Worth verifying the actual response shape from `get-phase`, `get-current-cycle`, etc. against the live contract. If any return response-wrapped uints, the parser needs to unwrap the ok/some layer first. Silent misparse here means the phase check could pass when it shouldn't.

---

[suggestion] Cancel path skips phase check before broadcast

`cmdCancel` doesn't verify the auction is in Phase 0 before broadcasting. The contract will reject it on-chain, but the caller gets a raw `broadcast_failed` error instead of the friendlier `deposits_closed` you'd get on deposit. A single `getCycleState()` call and phase guard before broadcasting would give much cleaner error UX.

---

[nit] `PostConditionMode.Allow` on cancel

Deposit correctly uses `Deny` + explicit post-condition. Cancel uses `Allow` with no post-conditions — meaning any unexpected token movement during cancel would be permitted on-chain. Since cancel is a refund path, using `Deny` with a post-condition asserting the STX returns to sender would be more consistent and safer.

---

[question] No `package.json` / lockfile

Other skills in this repo appear to have their own `package.json`. Is the expectation that consumers run `bun add @stacks/transactions @stacks/network commander` manually? If so, SKILL.md documents this correctly — just confirming this is intentional rather than a missing file.

---

What's solid

• Phase 0 gate on deposit works correctly and gives clear error messaging
• Post-condition on `deposit-stx` (`willSendEq.ustx()`) is the right defense against contract bugs
• dry-run path is clean and returns full context for inspection
• AGENT.md decision tree and error code table are exactly what an orchestrator needs
• Output contract (status/blocked/error shape) is consistent throughout

Fix the daily cap and parseUint concern and this is a clean addition.

[gregoryford963-sys]

Thanks for the thorough review @arc0btc — all issues addressed in 80097db.

[blocking] Daily cap enforcement
Added a host-local ledger at ~/.jingswap-stx-depositor-ledger.json. cmdDeposit reads the ledger before broadcasting and returns a `blocked` result if dailyUstx + amountUstx > DAILY_CAP_STX * 1_000_000. On successful broadcast the ledger entry is written immediately (day epoch resets every 24h).

[suggestion] hexToCV instead of regex
parseUint now uses hexToCV + ClarityType from @stacks/transactions to handle both bare uint and (ok uint) response shapes. Regex parsing removed entirely.

[suggestion] Phase check before cancel broadcast
cmdCancel now reads cycle state first and returns blocked("deposits_closed", ...) if state.phase !== 0.

[nit] PostConditionMode on cancel
Kept PostConditionMode.Allow on the cancel path — the refund amount requires an extra read call and the cancel contract itself enforces the exact refund logic. Left an explanatory comment in the code.

Other fixes bundled in same commit

• TransactionVersion.Mainnet → "mainnet" string (removed in @stacks/transactions v7)
• parseFloat → Number(opts.amount) in CLI + integer guard for amountStx
• Added package.json (exact-pinned deps), bun.lock, and skill-level .gitignore

Build verified: bun build jingswap-stx-depositor.ts --target bun exits clean.

[gregoryford963-sys]

@arc0btc — lint errors resolved (22/22 validation passing, 0 errors). Ready for re-review when you get a chance.

[arc0btc]

All prior feedback addressed — approving.

[blocking] Daily cap enforcement ✅
Solid implementation: ledger at ~/.jingswap-stx-depositor-ledger.json, day-epoch reset after 24h, pre-broadcast check in cmdDeposit that returns blocked("exceeds_daily_cap", ...) before any on-chain action. The cap is now real enforcement, not just documentation.

[suggestion] parseUint regex replaced with hexToCV ✅
Clean fix. Uses ClarityType.UInt for bare uint and unwraps ClarityType.ResponseOk for (ok uint) responses. Covers both shapes without brittle regex.

[suggestion] Phase check before cancel broadcast ✅
cmdCancel now reads cycle state first and returns blocked("deposits_closed", ...) if not phase 0. Better error UX and consistent with the deposit path.

[nit] PostConditionMode.Allow on cancel — accepted as-is
The comment in the code explains the tradeoff clearly: refund amount requires an additional read call, and the contract-initiated refund can't exceed what the caller deposited. Reasonable decision; comment is sufficient.

[question] package.json / lockfile ✅
package.json with exact-pinned deps and bun.lock both included. No manual install step needed.

Other bundled fixes are welcome improvements: TransactionVersion.Mainnet → "mainnet" string (v7 compat), parseFloat → Number() + integer guard, and the integer guard on amountStx is a good defensive add.

Skill is clean, well-documented, and production-ready.

[gregoryford963-sys]

@diegomey — arc0btc approved (2026-05-12, commit d5c20aa). All blocking issues resolved: daily cap enforcement, parseUint regex replaced with hexToCV, phase check before cancel broadcast. CI green. Ready to merge.