From 40fe0c509aea5b6a0370dd71a0c5532a978297bf Mon Sep 17 00:00:00 2001 From: Landyn Date: Tue, 5 May 2026 13:32:56 -0500 Subject: [PATCH 1/2] docs(llms.txt): clarify BTC env loading and reservation auto-extension Punch ran the agent quickstart end-to-end and snagged on two doc gaps: - `BTC_PRIVATE_KEY` only loads from a `.env` in the CWD where `alw` runs, but the doc didn't surface `export` as the equivalent CWD-agnostic path. Also added an explicit pointer for the most common error string so a panicked agent maps it back to "your env didn't reach the process". - BTC-source reservations look like they're about to expire when really validators are running the optimistic extension loop in the background. Spell that out so an agent watching the timer doesn't panic. --- public/llms.txt | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/public/llms.txt b/public/llms.txt index d3f1020..5137ec0 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -55,7 +55,8 @@ no wrapped asset, no bridge token. - `Min/Max Collateral` — what miners must lock; affects who can fulfill. - `Extension Challenge Window` / `Max Extension Length` / `Max Extensions per Reservation|Swap` — control how long swap deadlines can be auto-extended while you're awaiting confirmations. - `Consensus` — validator quorum required to advance a swap. -- **BTC fees gate the whole flow — underprice them and you lose your send.** For BTC-source swaps, validators only extend your reservation once the source tx has ≥1 confirmation (tier-1 extension is gated on `confirmations >= 1`). Set the fee too low and the tx sits in mempool: no confirmation → no extension → the reservation eventually times out *while your BTC is still in flight*. When it finally mines, it lands in the miner's address with no on-chain swap to credit it against, and the funds are gone. The CLI's auto-estimated `--btc-fee-rate` is intended to be a safe default — only override it if you've checked current mempool conditions (e.g. https://mempool.space), and never set it below a next-block tier. Same rule if you broadcast from your own wallet: validators cannot wait all day for a confirmation, so frugal fees = lost send. +- **Reservations auto-extend for BTC source — don't panic at the timer.** `alw view reservation` and `alw view swap --watch` show a TTL countdown that, on BTC-source swaps, will dip toward zero while you wait for confirmations. That's expected: validators run an optimistic propose/challenge/finalize loop that extends the reservation up to `Max Extensions / Reservation` times (see `alw view contract`) without any user action — tier-0 is granted on first ask, tier-1+ require `confirmations >= 1` on your source tx. If you've broadcast with a sane fee rate, sit tight; the timer recovers when the next extension finalizes. +- **BTC fees gate the whole flow — underprice them and you lose your send.** For BTC-source swaps, validators only extend your reservation past tier-0 once the source tx has ≥1 confirmation (tier-1 extension is gated on `confirmations >= 1`). Set the fee too low and the tx sits in mempool: no confirmation → no further extensions → the reservation eventually times out *while your BTC is still in flight*. When it finally mines, it lands in the miner's address with no on-chain swap to credit it against, and the funds are gone. The CLI's auto-estimated `--btc-fee-rate` is intended to be a safe default — only override it if you've checked current mempool conditions (e.g. https://mempool.space), and never set it below a next-block tier. Same rule if you broadcast from your own wallet: validators cannot wait all day for a confirmation, so frugal fees = lost send. - **Slash payouts are always TAO.** Even on BTC-side swaps you need a Bittensor wallet — that's where any timeout refund lands. - **Sender verification.** Validators reject any source tx whose on-chain sender does not match the address you proved at reserve time. Don't broadcast from any wallet other than the one tied to your reservation. @@ -166,7 +167,12 @@ Config persists at `~/.allways/config.json`. ### 4. (BTC-side only) BTC sending -For BTC→TAO swaps, the CLI can broadcast BTC for you if you put a WIF private key in a `.env` file in your **current working directory** when you run `alw` (the CLI loads `.env` from CWD, not `~/.allways/` and not the install path): +For BTC→TAO swaps, the CLI can broadcast BTC for you if you supply a WIF private key via env. **Two paths, both work — pick whichever fits your shell:** + +1. Drop a `.env` in the directory you'll run `alw` from. The CLI calls `dotenv` on the CWD only — *not* `~/.allways/`, *not* the install path, *not* a parent directory. If you `cd` elsewhere before running `alw`, the `.env` won't be picked up. +2. Or just `export` them in your current shell before invoking `alw` — equivalent and CWD-agnostic. + +The variables either way: BTC_MODE=lightweight BTC_NETWORK=mainnet @@ -174,6 +180,8 @@ For BTC→TAO swaps, the CLI can broadcast BTC for you if you put a WIF private `lightweight` mode talks to public Esplora-compatible APIs (Blockstream as primary, with a Mempool.space fallback if Blockstream is unreachable) — no Bitcoin node required. +If you see `BTC_MODE=lightweight requires BTC_PRIVATE_KEY env var`, the variable isn't reaching the process — either you ran `alw` from a directory without a `.env`, your `.env` is missing the key, or you didn't `export`. Confirm with `env | grep BTC_PRIVATE_KEY` before re-running. + If `BTC_PRIVATE_KEY` is unset, BTC→TAO falls back to a manual flow: the CLI prints the miner's address + exact amount, you broadcast from your own wallet, **then run `alw swap post-tx ` *within the reservation TTL window* (run `alw view contract` for the current value)**. Miss the window and the reservation expires before you can confirm. TAO→BTC swaps need no `.env` — your **coldkey** signs and sends the source TAO transfer directly. From 26bfa392ec936b80f1ca6c738cf1cfbbcf53d1ad Mon Sep 17 00:00:00 2001 From: Landyn Date: Tue, 5 May 2026 13:47:06 -0500 Subject: [PATCH 2/2] docs(llms): reflect new .env load order (shell > project walk-up > ~/.allways/.env) The CLI now loads env vars from three places in precedence order, so the doc no longer needs to warn agents about CWD-only behavior or push them toward `export` as a workaround. Trimmed the BTC sending block in both the static llms.txt and the in-app AgentMarkdown copy. --- public/llms.txt | 11 +++++------ src/components/agents/AgentMarkdown.ts | 8 +++++++- 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/public/llms.txt b/public/llms.txt index 5137ec0..58259e6 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -167,12 +167,13 @@ Config persists at `~/.allways/config.json`. ### 4. (BTC-side only) BTC sending -For BTC→TAO swaps, the CLI can broadcast BTC for you if you supply a WIF private key via env. **Two paths, both work — pick whichever fits your shell:** +For BTC→TAO swaps, the CLI can broadcast BTC for you if you supply a WIF private key via env. The CLI loads env vars from three places, in precedence order — first hit wins: -1. Drop a `.env` in the directory you'll run `alw` from. The CLI calls `dotenv` on the CWD only — *not* `~/.allways/`, *not* the install path, *not* a parent directory. If you `cd` elsewhere before running `alw`, the `.env` won't be picked up. -2. Or just `export` them in your current shell before invoking `alw` — equivalent and CWD-agnostic. +1. Your shell env (`export BTC_PRIVATE_KEY=...`). +2. A project `.env` walked up from your CWD (CWD, then each parent, until one is found). +3. A persistent `~/.allways/.env` (set-once, works from any directory). -The variables either way: +The variables, however you supply them: BTC_MODE=lightweight BTC_NETWORK=mainnet @@ -180,8 +181,6 @@ The variables either way: `lightweight` mode talks to public Esplora-compatible APIs (Blockstream as primary, with a Mempool.space fallback if Blockstream is unreachable) — no Bitcoin node required. -If you see `BTC_MODE=lightweight requires BTC_PRIVATE_KEY env var`, the variable isn't reaching the process — either you ran `alw` from a directory without a `.env`, your `.env` is missing the key, or you didn't `export`. Confirm with `env | grep BTC_PRIVATE_KEY` before re-running. - If `BTC_PRIVATE_KEY` is unset, BTC→TAO falls back to a manual flow: the CLI prints the miner's address + exact amount, you broadcast from your own wallet, **then run `alw swap post-tx ` *within the reservation TTL window* (run `alw view contract` for the current value)**. Miss the window and the reservation expires before you can confirm. TAO→BTC swaps need no `.env` — your **coldkey** signs and sends the source TAO transfer directly. diff --git a/src/components/agents/AgentMarkdown.ts b/src/components/agents/AgentMarkdown.ts index e404c5f..efe74c8 100644 --- a/src/components/agents/AgentMarkdown.ts +++ b/src/components/agents/AgentMarkdown.ts @@ -169,7 +169,13 @@ Config persists at \`~/.allways/config.json\`. ### 4. (BTC-side only) BTC sending -For BTC→TAO swaps, the CLI can broadcast BTC for you if you put a WIF private key in a \`.env\` file in your **current working directory** when you run \`alw\` (the CLI loads \`.env\` from CWD, not \`~/.allways/\` and not the install path): +For BTC→TAO swaps, the CLI can broadcast BTC for you if you supply a WIF private key via env. The CLI loads env vars from three places, in precedence order — first hit wins: + +1. Your shell env (\`export BTC_PRIVATE_KEY=...\`). +2. A project \`.env\` walked up from your CWD (CWD, then each parent, until one is found). +3. A persistent \`~/.allways/.env\` (set-once, works from any directory). + +The variables, however you supply them: BTC_MODE=lightweight BTC_NETWORK=mainnet