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

skills/dca/SKILL.md

@@ -13,8 +13,13 @@ metadata:
 
 # DCA — Dollar Cost Averaging for Stacks DeFi
 
-Automate recurring token purchases (or sales) on Stacks mainnet via **direct Bitflow swaps**.
-The agent executes each order on schedule — no third-party contracts required.
+## What it does
+
+Automates recurring token purchases or sales on Stacks mainnet via direct Bitflow swaps. The agent executes each order on schedule with slippage guardrails, balance pre-checks, and confirmation gates — no third-party contracts required.
+
+## Why agents need it
+
+Autonomous agents holding STX or sBTC need a disciplined, hands-off way to accumulate target assets over time without market-timing risk. DCA removes the decision loop — the agent sets a plan once and calls `run` on each tick; the skill handles quotes, safety checks, and execution.
 
 ## How It Works
 
@@ -136,7 +141,7 @@ Pass `--total` in **human-readable units** (not microunits):
 | `STACKS_PRIVATE_KEY` | Direct private key for testing (bypasses wallet file) |
 | `AIBTC_DRY_RUN=1` | Simulate all writes — no transactions broadcast |
 
-## Output Format
+## Output contract
 
 All commands emit strict JSON to stdout:
 
@@ -152,6 +157,14 @@ All commands emit strict JSON to stdout:
 }
 ```
 
+## Safety notes
+
+- **Writes to chain.** `run --confirm` broadcasts a Stacks swap transaction.
+- **Moves funds.** Each confirmed order transfers your input token to Bitflow. Ensure wallet is funded before scheduling.
+- **Mainnet only.** Bitflow routes are production mainnet — not available on testnet.
+- **Confirmation required.** Every order returns `blocked` without `--confirm`. Never passes `--confirm` autonomously without verifying the quote first.
+- **Balance checked at execution.** Insufficient STX halts the order with `INSUFFICIENT_BALANCE`.
+
 ## Safety Guardrails (enforced in code)
 
 | Guardrail | Limit | Enforcement |

skills/jingswap-stx-depositor/.gitignore

@@ -0,0 +1 @@
+node_modules/

skills/jingswap-stx-depositor/AGENT.md

@@ -0,0 +1,81 @@
+---
+name: jingswap-stx-depositor-agent
+skill: jingswap-stx-depositor
+description: "Direct on-chain JingSwap STX auction deposit agent. Deposits STX into blind batch auctions and cancels deposits via makeContractCall — no MCP relay needed."
+---
+
+# jingswap-stx-depositor — Agent Usage
+
+## One-line summary
+Deposit STX into JingSwap blind batch auctions with direct on-chain transactions.
+
+## Guardrails
+
+- NEVER deposit in Phase 1 or Phase 2 — skill enforces this and returns `deposits_closed`
+- NEVER deposit if `data.total_sbtc_deposited_sats === 0` — no sBTC means no settlement counterparty
+- NEVER exceed 5,000 STX per operation or 20,000 STX per day
+- Always run `status` first to verify phase before depositing
+- Always use `--dry-run` before live broadcast on a new wallet or amount
+
+## Decision order
+
+1. `status` → check `data.accepting_deposits` (must be `true`) and `data.total_sbtc_deposited_sats` (must be > 0)
+2. `deposit --amount <stx> --dry-run` → verify safety checks pass
+3. `deposit --amount <stx>` → broadcast; capture `data.txid`
+4. If phase changes to 1 or 2 while deposit is pending: do NOT cancel — await settlement
+
+## When to use
+- Agent wants to exchange idle STX for sBTC via JingSwap's oracle-priced batch settlement
+- Rebalancing loop detects STX oversupply and wants to acquire sBTC at oracle price
+- Agent needs to cancel a pending deposit before settlement
+
+## Workflow
+
+1. **Check auction phase**
+```bash
+bun run jingswap-stx-depositor.ts status
+```
+Only proceed if `data.accepting_deposits === true` (phase 0).
+
+2. **Verify sBTC is in the pool**
+Check `data.total_sbtc_deposited_sats > 0` — if no sBTC depositors, your STX won't fill.
+
+3. **Dry run**
+```bash
+bun run jingswap-stx-depositor.ts deposit --amount 100 --dry-run
+```
+
+4. **Execute on-chain**
+```bash
+bun run jingswap-stx-depositor.ts deposit --amount 100
+```
+Capture `data.txid` and `data.explorer_url`.
+
+5. **Cancel if needed (phase 0 only)**
+```bash
+bun run jingswap-stx-depositor.ts cancel
+```
+
+## Error codes
+
+| Code | Meaning | Fix |
+|---|---|---|
+| `no_wallet` | CLIENT_PRIVATE_KEY not set | Export key |
+| `deposits_closed` | Auction in phase 1 or 2 | Wait for next cycle |
+| `below_minimum` | Amount under auction minimum | Increase --amount |
+| `insufficient_balance` | Not enough STX | Fund wallet |
+| `exceeds_per_op_cap` | Over 5,000 STX | Lower --amount |
+| `broadcast_failed` | Stacks node rejected tx | Check logs |
+
+## Settlement mechanics
+
+JingSwap settles at the Pyth BTC/STX oracle price at cycle close. Your STX deposit fills proportionally against sBTC depositors. The final exchange rate is set on-chain — no slippage, no front-running.
+
+## Environment setup
+
+```bash
+export CLIENT_PRIVATE_KEY=<your_stacks_private_key_hex>
+cd skills/jingswap-stx-depositor
+bun install
+bun run jingswap-stx-depositor.ts status
+```

skills/jingswap-stx-depositor/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: jingswap-stx-depositor
+description: "Direct on-chain JingSwap STX→sBTC blind batch auction depositor. Broadcasts deposit-stx and cancel-stx-deposit transactions directly via @stacks/transactions — no MCP relay required."
+metadata:
+  author: "gregoryford963-sys"
+  author-agent: "369SunRay"
+  user-invocable: "false"
+  arguments: "status | deposit --amount <stx> [--dry-run] | cancel [--dry-run]"
+  entry: "jingswap-stx-depositor/jingswap-stx-depositor.ts"
+  requires: "wallet, CLIENT_PRIVATE_KEY"
+  tags: "jingswap, sbtc, stx, defi, write, direct-broadcast, mainnet-only, stacks"
+---
+
+# jingswap-stx-depositor
+
+Direct on-chain JingSwap STX→sBTC blind batch auction depositor.
+
+## Why agents need it
+
+JingSwap auctions settle at the live Pyth BTC/STX oracle price — not an AMM curve — giving agents oracle-priced sBTC acquisition without slippage or front-running. The existing `jingswap-cycle-agent` skill requires a parent agent to relay the deposit via the `jingswap_deposit_stx` MCP tool. This skill eliminates that relay: it calls `deposit-stx` and `cancel-stx-deposit` directly on-chain and returns the confirmed `txid` immediately.
+
+## Safety notes
+
+- `deposit` requires Phase 0 (deposit window) — rejected in Phase 1 or 2 with a `deposits_closed` error.
+- Post-condition on every deposit: `Pc.principal(wallet).willSendEq(amount).ustx()` — transaction aborts on-chain if the wrong amount leaves the wallet.
+- Per-op cap: 5,000 STX. Daily cap: 20,000 STX. Gas reserve: 1 STX always kept.
+- `cancel` can only succeed if a deposit exists and the cycle is still in Phase 0.
+- Mainnet only — `sbtc-stx-jing-v2` is mainnet-only.
+
+## What it does
+
+Participates in JingSwap's STX/sBTC blind batch auctions by broadcasting `deposit-stx` and `cancel-stx-deposit` transactions directly via `@stacks/transactions`. No MCP relay — every write call goes on-chain from this process.
+
+JingSwap auctions run in cycles:
+- **Phase 0 (deposit):** STX depositors and sBTC depositors enter the pool
+- **Phase 1 (buffer):** Deposits close, settlement pending
+- **Phase 2 (settle):** Oracle price (Pyth BTC/STX) used to fill both sides proportionally
+
+## Contract
+
+- **Address:** `SPV9K21TBFAK4KNRJXF5DFP8N7W46G4V9RCJDC22`
+- **Contract:** `sbtc-stx-jing-v2`
+- **Write functions:**
+  - `deposit-stx(amount: uint)` — deposit `amount` uSTX, post-condition enforces exact transfer
+  - `cancel-stx-deposit()` — cancel deposit and reclaim STX before cycle settles
+
+## Commands
+
+### `status`
+Read current cycle phase, totals, and minimum deposit requirements.
+```
+bun run jingswap-stx-depositor.ts status
+```
+
+### `deposit --amount <stx> [--dry-run]`
+Deposit STX into the current cycle. Only works in Phase 0.
+```
+# Dry run — simulate
+bun run jingswap-stx-depositor.ts deposit --amount 100 --dry-run
+
+# Live broadcast
+bun run jingswap-stx-depositor.ts deposit --amount 100
+```
+
+### `cancel [--dry-run]`
+Cancel your current STX deposit and reclaim funds.
+```
+bun run jingswap-stx-depositor.ts cancel
+```
+
+## Environment
+
+| Variable | Purpose |
+|---|---|
+| `CLIENT_PRIVATE_KEY` | Stacks private key (hex, with or without `01` suffix) |
+| `STACKS_PRIVATE_KEY` | Fallback alias |
+
+## Safety limits
+
+| Limit | Value |
+|---|---|
+| Per-op cap | 5,000 STX |
+| Daily cap | 20,000 STX |
+| Gas reserve | 1 STX kept post-deposit |
+| TX fee | 0.003 STX |
+| Post-condition | `Pc.principal(wallet).willSendEq(amount).ustx()` — aborts if wrong amount leaves wallet |
+
+## Output contract
+
+All outputs are newline-delimited JSON to stdout.
+
+**Success (deposit):**
+```json
+{
+  "status": "success",
+  "action": "deposited",
+  "data": {
+    "txid": "abc123...",
+    "explorer_url": "https://explorer.hiro.so/txid/0xabc123?chain=mainnet",
+    "amount_stx": 100,
+    "amount_ustx": 100000000,
+    "cycle": 42,
+    "wallet": "SP...",
+    "safety_checks": {}
+  },
+  "error": null
+}
+```
+
+**Blocked:**
+```json
+{ "status": "blocked", "action": "deposits_closed", "data": null, "error": { "code": "deposits_closed", "message": "...", "next": "..." } }
+```
+
+**Error:**
+```json
+{ "status": "error", "action": "broadcast_failed", "data": null, "error": { "code": "broadcast_failed", "message": "...", "next": "..." } }
+```
+
+## Dependencies
+
+```
+bun add @stacks/transactions @stacks/network commander
+```
+
+## Agent decision guide
+
+```
+if status.accepting_deposits === true:
+  if status.total_sbtc_deposited_sats > 0:
+    # sBTC is in pool — STX deposit will fill
+    deposit --amount <stx>
+  else:
+    # No sBTC yet — wait for sBTC depositors
+    skip
+
+if holding deposit and phase != 0:
+  # Cannot cancel — wait for settlement
+  monitor
+```
+
+For agents: Run `status` to check phase before depositing. If phase changes to 1 or 2 after depositing, settlement is pending — do not attempt to cancel.