aibtcdev/zest-asset-deposit-primitive

Zest Asset Deposit Primitive

What it does

zest-asset-deposit-primitive deposits an existing wallet asset into Zest V2 collateral through v0-4-market.supply-collateral-add.

It is a primitive write skill: one Zest collateral-add action, one transaction, proof-ready JSON output.

Why agents need it

Agents need a standalone collateral-entry primitive before they can safely compose borrow, repay, leverage, unwind, or cross-protocol routing flows.

Safety notes

• Mainnet only.
• This is a write skill and can move funds.
• run refuses to broadcast without --confirm=DEPOSIT.
• The skill verifies the Zest V2 market, selected asset, paired vault, current wallet balance, share conversion, pending transaction depth, signer address, and postcondition plan before broadcast.
• Transactions use PostConditionMode.Deny.
• FT deposits include postconditions for wallet underlying spend, Market underlying spend, and wallet vault-share movement.
• STX deposits use the wrapper's native STX transfer behavior, but the current public proof covers only sBTC.
• The skill blocks if a nonzero deposit converts to zero vault shares.
• The skill blocks unsupported live egroup masks before broadcast.
• It is not a borrow, repay, withdraw, faucet, swap, leverage loop, or HODLMM skill.

Commands

doctor

bun run zest-asset-deposit-primitive/zest-asset-deposit-primitive.ts doctor --wallet <stacks-address> --deposit-asset sBTC

status

bun run zest-asset-deposit-primitive/zest-asset-deposit-primitive.ts status --wallet <stacks-address> --deposit-asset sBTC --amount <base-units>

plan

bun run zest-asset-deposit-primitive/zest-asset-deposit-primitive.ts plan --wallet <stacks-address> --deposit-asset sBTC --amount <base-units>

run

bun run zest-asset-deposit-primitive/zest-asset-deposit-primitive.ts run --wallet <stacks-address> --deposit-asset sBTC --amount <base-units> --confirm=DEPOSIT

Without --confirm=DEPOSIT, run blocks before signer resolution and before broadcast.

Output contract

Every command prints exactly one JSON object to stdout.

Success:

{ "status": "success", "action": "status", "data": {}, "error": null }

Blocked:

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

Known constraints

• The initial proof path uses sBTC because the proof wallet already has a Zest sBTC collateral position and that live egroup admits same-collateral top-ups.
• Supported assets in this version are limited to STX, sBTC, and USDC / USDCx. Other live Zest V2 assets such as stSTX, USDH, and stSTXbtc are not implemented yet and will return an unsupported-asset error.
• STX deposit support is implemented from the live wrapper path but is not yet covered by a mainnet proof transaction in this PR.
• Adding a different collateral class to an existing Zest account can be blocked by the live egroup registry. The skill checks this and blocks before broadcast.
• price-feeds are currently passed as none; same-collateral top-ups and no-debt collateral adds do not need a fresh oracle write in the verified proof path.

Origin

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