Skip to content

Commit 43964a1

Browse files
web3jenksweb3jenks
committed
Add TBV agent runbook
1 parent 8e27430 commit 43964a1

4 files changed

Lines changed: 146 additions & 0 deletions

File tree

‎docs/trustless-bitcoin-vault/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ Lookup material:
6060

6161
- **[Glossary](./reference/glossary.mdx)** — terms used throughout the docs.
6262
- **[Community & support](./reference/community-and-support.mdx)** — Discord, GitHub, contact channels.
63+
- **[Agent runbook](./reference/agent-runbook.mdx)** — public Testnet instructions for browser and CLI agents.
6364

6465
## Two layers
6566

‎docs/trustless-bitcoin-vault/reference/agent-runbook.mdx‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
title: Agent runbook
3+
sidebar_position: 3
4+
---
5+
6+
# Agent runbook
7+
8+
This page is for AI and automation agents working with the Babylon Trustless Bitcoin Vault (TBV) public Testnet. It summarizes the public workflow, safety boundaries, and evidence expectations for agents that operate either through a browser with wallets or through BabyTester CLI UATs.
9+
10+
Use this only for public Testnet flows on Bitcoin signet and Ethereum Sepolia. Do not use it for mainnet funds, wallet creation, seed handling, faucet account management, or private deployment operations.
11+
12+
## Safety boundaries
13+
14+
Agents must:
15+
16+
* Use only `https://btc-vaults.testnet.babylonlabs.io/` for browser testing.
17+
* Treat wallet prompts as real user-profile actions, even when assets are testnet-only.
18+
* Stop before confirming if the wallet domain, network, contract, amount, or action differs from the expected TBV Testnet flow.
19+
* Never request, store, repeat, screenshot intentionally, or commit seed phrases, private keys, passwords, wallet unlock material, cookies, or recovery artifact contents.
20+
* Record recovery artifact file paths only. Do not copy artifact contents into notes, chat logs, repos, or tickets.
21+
22+
## Public Testnet target
23+
24+
Use the values from [Setup](../testnet-info/setup.mdx) as canonical. At a high level:
25+
26+
| Item | Value |
27+
| --- | --- |
28+
| Test app | `https://btc-vaults.testnet.babylonlabs.io/` |
29+
| Bitcoin network | signet |
30+
| Ethereum network | Sepolia, chain ID `11155111` |
31+
| Primary faucet | `https://tbv-faucet.testnet.babylonlabs.io/` |
32+
| Bitcoin explorer | `https://mempool.space/signet` |
33+
| Ethereum explorer | `https://sepolia.etherscan.io/` |
34+
35+
The Bitcoin wallet must use Taproot (P2TR) before connecting. UniSat on signet is the documented browser-wallet path. Ethereum wallet actions occur on Sepolia.
36+
37+
## Browser and computer-use agents
38+
39+
Browser agents should use the user's real Chrome profile when wallet extensions are required. Clean automation profiles generally cannot operate installed UniSat or MetaMask sessions, and extension popups often require desktop-control tooling.
40+
41+
Before wallet-affecting actions, confirm:
42+
43+
* deposit amount
44+
* borrow amount and asset
45+
* full or partial repay intent
46+
* fresh run or resume
47+
* whether recovery artifacts should be downloaded before activation
48+
49+
Do not invent default amounts for wallet actions. If funded test assets are missing, pause and ask the user to fund through the public Testnet faucet process.
50+
51+
### Expected browser lifecycle
52+
53+
1. Open the TBV Testnet app.
54+
2. Inspect current app state before starting or resuming.
55+
3. Connect the Bitcoin wallet on signet using Taproot.
56+
4. Connect the Ethereum wallet on Sepolia.
57+
5. Create a vault with the confirmed deposit amount.
58+
6. Complete UniSat and Ethereum wallet signing steps.
59+
7. Wait for Bitcoin confirmations and provider-side verification.
60+
8. Complete payout and recovery signing checkpoints when prompted.
61+
9. Download recovery artifacts if requested.
62+
10. Activate the vault.
63+
11. Borrow the confirmed asset and amount.
64+
12. Repay the intended amount, using max/full only when requested.
65+
13. Select the relevant vault row if withdraw controls are disabled.
66+
14. Initiate withdraw and record the final app-side state.
67+
68+
Report app-side withdraw initiation separately from BTC-side settlement. `Withdraw Initiated`, `Pending Withdraw`, and final Bitcoin payout are different states.
69+
70+
### Resume guidance
71+
72+
Inspect before acting. A resumed peg-in can be safer than starting over.
73+
74+
* If a pending deposit shows a signing-required state, continue with payout or recovery signing.
75+
* If the app shows provider verification or ACK collection, wait and refresh before retrying actions.
76+
* Ready to activate is not active collateral; activation still requires an Ethereum transaction.
77+
* If debt is repaid but withdraw is unavailable, check whether the target vault row must be selected.
78+
79+
## BabyTester CLI agents
80+
81+
BabyTester is the UAT executor for TBV lifecycle validation. Use only public-facing commands and behavior from BabyTester when preparing agent instructions. It supports ad-hoc CLI runs, scheduled server mode, SQLite persistence, read-only HTTP APIs, and a dashboard showing UAT status, runs, step timelines, evidence, and logs.
82+
83+
Public CLI commands:
84+
85+
```bash
86+
pnpm dev -- list
87+
pnpm dev -- test pegin --verbose
88+
pnpm dev -- test --all
89+
pnpm dev -- test --all --parallel --concurrency 2
90+
pnpm dev -- serve --config environments/devnet.toml --verbose
91+
pnpm dev -- serve --no-scheduler --verbose
92+
```
93+
94+
Use environment files only by named reference. Do not publish or paste private key variables, RPC credentials, deployment secrets, or private `.env` content.
95+
96+
BabyTester stores run results and logs locally and writes JSON/Markdown reports under `results/`. Its API listens on `http://127.0.0.1:3100` by default and exposes public run-inspection surfaces such as health, UAT list, run list, run detail, and logs.
97+
98+
### Public UAT surfaces
99+
100+
BabyTester exposes UAT modules for:
101+
102+
* `pegin`: end-to-end vault creation, WOTS generation, Ethereum registration, Bitcoin transaction submission, presigning, verification, and activation.
103+
* `batch-pegin`: multi-vault peg-in flow.
104+
* `lending-flow`: active collateral, borrow, interest accrual, repay, max repay, and over-repay refund behavior.
105+
* `pegout-happy-path`: repay debt, withdraw collateral, redeem vaults, and monitor peg-out.
106+
* peg-out challenge paths: wrongly challenged and challenger-wins scenarios.
107+
* liquidation paths: Vault Swap liquidation, fairness checks, direct redemption, and BTC payout monitoring.
108+
* `vault-reordering`: position vault-order updates and on-chain ordering verification.
109+
* `cap-policy`: cap read paths, cap lowering, activation effects, and auto-redeem behavior.
110+
* pause/freeze state machines for protocol-level and application-level controls.
111+
* AML early-reject behavior.
112+
113+
## Evidence expectations
114+
115+
For browser runs, create a dated evidence folder and capture screenshots before critical wallet approvals, after success modals, before activation, after activation, after repay, and on the final dashboard state.
116+
117+
For CLI runs, preserve the BabyTester run ID, command, selected UAT name, environment name, report path, and relevant transaction hashes.
118+
119+
Final reports should state whether these passed:
120+
121+
* deposit activation
122+
* borrow
123+
* repay, including full or partial
124+
* withdraw initiation, if attempted
125+
126+
Also include:
127+
128+
* evidence folder or report path
129+
* recovery artifact path, if downloaded
130+
* any wallet/app divergence from the expected path
131+
* whether BTC-side settlement is still pending
132+
133+
## Related pages
134+
135+
* [Setup](../testnet-info/setup.mdx)
136+
* [Quickstart](../use-for-lending/quickstart.mdx)
137+
* [Create a vault](../use-for-lending/create-a-vault.mdx)
138+
* [Borrow & repay](../use-for-lending/borrow-and-repay.mdx)
139+
* [Withdraw & redeem](../use-for-lending/withdraw-and-redeem.mdx)
140+
* [Liquidation risk](../use-for-lending/liquidation-risk.mdx)

‎sidebars-default.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -328,6 +328,7 @@ const sidebars = {
328328
items: [
329329
'trustless-bitcoin-vault/reference/glossary',
330330
'trustless-bitcoin-vault/reference/community-and-support',
331+
'trustless-bitcoin-vault/reference/agent-runbook',
331332
],
332333
},
333334
...trustlessBitcoinVaultSecuritySection,

‎static/robots.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,9 @@ User-agent: *
22
Allow: /
33
Allow: /llms.txt
44
Allow: /llms-ctx.txt
5+
Allow: /llms-full.txt
6+
Allow: /llms-tbv.txt
7+
Allow: /llms-tbv-ctx.txt
8+
Allow: /llms-tbv-full.txt
59

610
Sitemap: https://docs.babylonlabs.io/sitemap.xml

0 commit comments

Comments
 (0)