| name | bitflow-zest-sbtc-leverage-cycle |
| description | Composes Zest borrow, Bitflow swap, and Zest deposit primitives into one sBTC leverage cycle. |
| metadata | {"author":"macbotmini-eng","author-agent":"Hex Stallion","user-invocable":"false","arguments":"doctor | status | plan | run | resume | cancel","entry":"bitflow-zest-sbtc-leverage-cycle/bitflow-zest-sbtc-leverage-cycle.ts","requires":"wallet, signing, settings, zest-borrow-asset-primitive, bitflow-swap-aggregator, zest-asset-deposit-primitive","tags":"defi, write, mainnet-only, requires-funds, infrastructure, l2"} |
Bitflow + Zest sBTC Leverage Cycle
What it does
bitflow-zest-sbtc-leverage-cycle coordinates one forward sBTC leverage cycle by composing three primitive skills:
- borrow STX against existing Zest sBTC collateral with
zest-borrow-asset-primitive,
- swap borrowed STX to sBTC with
bitflow-swap-aggregator,
- deposit the received sBTC back into Zest collateral with
zest-asset-deposit-primitive.
This is a controller, not a primitive. It must not rebuild the borrow, swap, or deposit transactions internally. It calls the primitive skill CLIs, parses their JSON results, saves progress after each confirmed leg, and refuses to continue when a required primitive is missing or returns a blocked/error result.
This is not a continuous best-yield monitor and not a close-position unwind. Closing the debt position requires a separate unwind path: repay, redeem collateral, and optionally swap back.
Why agents need it
Leveraged sBTC is a multi-leg operation. An agent needs an ordered coordinator that can stop after a partial completion, resume from the saved point, and keep the transaction-building risk inside reviewed primitive skills.
Dependency diagram
flowchart TD
A["Existing Zest sBTC collateral"] --> B["zest-borrow-asset-primitive: borrow STX"]
B --> C["checkpoint: borrow_confirmed"]
C --> D["bitflow-swap-aggregator: swap STX to sBTC"]
D --> E["checkpoint: swap_confirmed"]
E --> F["zest-asset-deposit-primitive: deposit sBTC collateral"]
F --> G["checkpoint: complete"]
Safety notes
- This is a composed write skill and can create debt and move funds.
- It requires existing Zest sBTC collateral.
run and write-capable resume require --confirm=CYCLE.- It blocks if
zest-borrow-asset-primitive, bitflow-swap-aggregator, or zest-asset-deposit-primitive is not installed.
- It never imports source from another skill directory.
- It shells out to primitive CLIs and only trusts one JSON object from each primitive.
- It saves checkpoint state after each successful write leg.
- It refuses a new cycle when unresolved state exists.
- It uses each primitive's own confirmation token:
BORROW, SWAP, and DEPOSIT.
- It does not claim proof readiness until the dependency primitives are accepted and the composed run itself has mainnet proof.
Commands
doctor
Checks dependency presence, saved-state status, and primitive readiness where the primitive CLIs are installed.
bun run bitflow-zest-sbtc-leverage-cycle/bitflow-zest-sbtc-leverage-cycle.ts doctor --wallet <stacks-address>
status
Reports dependency presence and saved cycle state. When dependencies are installed, it also asks the Zest primitives for read-only position status.
bun run bitflow-zest-sbtc-leverage-cycle/bitflow-zest-sbtc-leverage-cycle.ts status --wallet <stacks-address>
plan
Builds an ordered plan by calling primitive plan commands without broadcasting.
bun run bitflow-zest-sbtc-leverage-cycle/bitflow-zest-sbtc-leverage-cycle.ts plan --wallet <stacks-address> --borrow-amount-ustx <uSTX>
run
Executes one composed cycle only after explicit confirmation.
bun run bitflow-zest-sbtc-leverage-cycle/bitflow-zest-sbtc-leverage-cycle.ts run --wallet <stacks-address> --borrow-amount-ustx <uSTX> --confirm=CYCLE
resume
Continues only from a saved borrow_confirmed or swap_confirmed checkpoint after explicit confirmation.
bun run bitflow-zest-sbtc-leverage-cycle/bitflow-zest-sbtc-leverage-cycle.ts resume --wallet <stacks-address> --confirm=CYCLE
cancel
Marks an unresolved saved cycle as operator-cancelled.
bun run bitflow-zest-sbtc-leverage-cycle/bitflow-zest-sbtc-leverage-cycle.ts cancel --wallet <stacks-address>
Output contract
Every command prints exactly one JSON object to stdout.
{
"status": "success|blocked|error",
"action": "doctor|status|plan|run|resume|cancel",
"data": {},
"error": null
}
Known constraints
- This controller is sBTC-specific by design.
- The first cycle path is sBTC collateral, STX borrow, STX to sBTC swap, and sBTC collateral deposit.
- The dependency primitives are separate PRs. Until they are merged or otherwise installed in the runtime, this controller should remain draft and will block on missing dependencies.
- It does not perform HODLMM LP deposit/withdrawal.
- It does not repay, unwind, redeem collateral, or close debt.
- It does not continuously monitor yield opportunities.
Origin
Winner of AIBTC x Bitflow Skills Pay the Bills competition.
Original author: @macbotmini-eng
Competition PR: https://github.com/BitflowFinance/bff-skills/pull/578
