zest-borrow-asset-primitive

What this skill does

# Zest Borrow Asset Primitive

## What it does

`zest-borrow-asset-primitive` borrows a selected Zest V2-supported asset against an existing V2 collateral position on Stacks mainnet. It is a primitive write skill: one operator-selected amount, one Zest V2 borrow transaction, and proof-ready JSON output.

The skill is market-aware but not strategy-specific: callers choose `--collateral-asset`, `--borrow-asset`, and `--amount`, and the skill validates those choices against the live Zest registry before planning or broadcasting. It does not supply collateral, swap borrowed assets, run a leverage loop, repay debt, or unwind a position.

## Why agents need it

Leveraged sBTC workflows need a proven borrow leg before any controller can safely compose borrow, swap, and re-supply steps. This skill isolates the debt-creating action so it can be reviewed, proved, and reused without hiding borrow risk inside a larger strategy.

## Safety notes

- This is a write skill and can create debt.
- It requires existing Zest collateral before borrowing.
- It requires explicit `--confirm=BORROW` before broadcast.
- It verifies the configured Zest V2 market, vault, assets, and egroup contracts before a write.
- It reads selected asset, LP token, oracle, reserve, collateral, debt, gas, and pending transaction state before planning or running.
- It uses `PostConditionMode.Deny` with an asset transfer postcondition for the borrowed asset where expressible.
- For non-STX borrowed assets, the postcondition uses the SIP-010 asset name, not the contract name.
- It calls `v0-4-market.borrow` directly; legacy helper contracts are not the submission target.
- It treats `borrow-helper-v2-1-7` and `borrow-helper-v2-1-5` as legacy/non-target paths for this V2 primitive.
- It blocks when the sender has pending STX transactions.
- It checks the signer address against `--wallet`.
- It resolves the existing AIBTC wallet/runtime first and does not create or import a wallet.
- It does not hardcode proof wallets, amounts, or proof-only signer behavior.

## Commands

### doctor

Checks live Zest contract/interface readiness, wallet gas, pending transaction depth, and selected asset support. If asset flags are omitted, `doctor` uses a baseline supported-asset pair only for dependency readiness; that default pass does not prove readiness for every supported asset pair.

```bash
bun run zest-borrow-asset-primitive/zest-borrow-asset-primitive.ts doctor --wallet <stacks-address>
```

If `doctor` returns `UNSUPPORTED_*` for any dependency, stop. Re-verify the Zest contract identifier against live protocol sources or Hiro before planning a borrow.

### status

Reads current collateral/debt state for the selected collateral and borrow assets.
Requires explicit `--collateral-asset` and `--borrow-asset`; strategy commands do not infer the market from defaults.

```bash
bun run zest-borrow-asset-primitive/zest-borrow-asset-primitive.ts status --wallet <stacks-address> --collateral-asset sBTC --borrow-asset STX
```

### plan

Builds a read-only borrow preview, including contract arguments, postcondition plan, pending depth, current position data, and proof obligations.
Requires explicit `--collateral-asset`, `--borrow-asset`, and `--amount`.

```bash
bun run zest-borrow-asset-primitive/zest-borrow-asset-primitive.ts plan --wallet <stacks-address> --collateral-asset sBTC --borrow-asset STX --amount <base-units>
```

`--amount` is always in base units for the selected borrow asset. `STX` is accepted as an operator-facing alias for Zest `wSTX`, and other supported assets use their live registry token, asset name, LP token, oracle, and decimals.

### run

Rechecks live state, resolves a signer, broadcasts only after explicit confirmation, and returns proof JSON.
Requires explicit `--collateral-asset`, `--borrow-asset`, `--amount`, and `--confirm=BORROW`.

```bash
bun run zest-borrow-asset-primitive/zest-borrow-asset-primitive.ts run --wallet <stacks-address> --collateral-asset sBTC --borrow-asset STX --amount <base-units> --confirm=BORROW
```

Without `--confirm=BORROW`, `run` refuses before signer resolution or transaction construction.

## Output contract

All commands print one JSON object to stdout with this envelope:

```json
{ "status": "success|blocked|error", "action": "doctor|status|plan|run", "data": {}, "error": null }
```

Success:

```json
{ "status": "success", "action": "plan", "data": {}, "error": null }
```

Blocked:

```json
{
  "status": "blocked",
  "action": "run",
  "data": {},
  "error": {
    "code": "CONFIRMATION_REQUIRED",
    "message": "This write skill requires explicit confirmation.",
    "next": "Re-run with --confirm=BORROW."
  }
}
```

Error:

```json
{ "status": "error", "action": "run", "data": {}, "error": { "code": "ERROR", "message": "...", "next": "Inspect the error and rerun doctor." } }
```

## Known constraints

- Mainnet only.
- The first proof collateral path is sBTC collateral and the first proof borrow path is STX, but both are selected through runtime CLI inputs.
- `STX` is treated as the Zest wrapped STX asset (`wSTX`) for the borrow contract.
- This skill only borrows; it does not enable collateral, supply collateral, swap, repay, or rebalance.
- The verified V2 borrow target is `SP1A27KFY4XERQCCRCARCYD1CC5N7M6688BSYADJ7.v0-4-market.borrow`.
- The V2 borrow ABI is positional: `ft`, `amount`, `receiver`, `price-feeds`; `receiver` must be an optional principal such as `(some --wallet)`.
- Zest's exact global health calculation is enforced inside the V2 market borrow path. The skill reads public Zest state and refuses obvious unsafe setups, but PR proof must include successful on-chain execution and post-borrow status showing updated debt before any leverage controller can depend on it.
- `scaledDebt` is index-scaled principal, not the exact repayment amount. Status output includes debt-index fields and estimated current debt when the borrow vault exposes them.
- Some Zest V2 assets intentionally share a base oracle feed and apply a Market callcode transform. Status output includes the live registry oracle tuple so downstream controllers can see the feed id and callcode used by the selected collateral and borrow assets.
- Single-borrow nonce safety is in scope: the skill blocks when the sender already has pending STX transactions. Standalone/cross-skill nonce serialization belongs in the existing nonce runtime primitives and later composed controllers.

## Origin

Winner of AIBTC x Bitflow Skills Pay the Bills competition.
Original author: @macbotmini-eng
Competition PR: https://github.com/BitflowFinance/bff-skills/pull/572