@temporalabs/treasury 0.1.3 → 0.1.4

package/llms.txt

@@ -3,8 +3,8 @@
 > Agent Treasury by Tempora Labs — a depositor client for ERC-4626 vaults and a Kamino vault on Solana: registry, pre-flight, and unsigned deposit/withdraw builders. Never signs, never holds a key.
 
 This file is generated from the earn skill and from the command descriptions `treasury --help` prints; it is not edited by hand.
-This version's copy is at https://raw.githubusercontent.com/TemporaLabs/treasury/v0.1.3/llms.txt.
-Run commands as `treasury <skill> <command> [--flag value …]` (`npx @temporalabs/treasury@0.1.3 …` runs the same version without installing it). Each prints one JSON document.
+This version's copy is at https://raw.githubusercontent.com/TemporaLabs/treasury/v0.1.4/llms.txt.
+Run commands as `treasury <skill> <command> [--flag value …]` (`npx @temporalabs/treasury@0.1.4 …` runs the same version without installing it). Each prints one JSON document.
 
 # The earn skill
 
@@ -17,7 +17,7 @@ not permission to deposit it. **How much to deposit or withdraw is the operator'
 not pick.** Not a small test amount, not a round number, not the wallet's balance: if the operator has
 not named an amount, ask for one before you quote. The
 `treasury` CLI gives you eight `earn` commands that read the vault and **prepare unsigned
-calls**, and five `connect` commands that put those calls in front of the operator's own wallet in a
+calls**, and six `connect` commands that put those calls in front of the operator's own wallet in a
 browser page. Run each one with the shell, exactly like this (nothing stays running between commands):
 
 ```bash
@@ -142,41 +142,48 @@ bridge. An operator can still put money into several vaults, on one chain or sev
 
 ### Several vaults in one request
 
-An operator can spread money across vaults in one sitting — "1 USDC on Base and 3 on Solana", "2 USDC on every chain",
-"1 in 2B and 1 in 2E". The vaults may be on different chains or the same one. That is **one deposit per vault**, each a
-complete deposit of its own with its own transaction; nothing moves money into several vaults at once.
-
-1. **Settle the list from the operator's own words.** Each vault, its chain and its amount. A chain named
-   without a vault means that chain's default vault. "Every chain" means every entry in `earn_vaults` →
-   `chains`, each with its default vault; "every vault" means every vault in `earn_vaults` →
-   `depositable`. A listed vault that is not in `depositable` cannot take the deposit: name it to the
-   operator rather than dropping it silently. Do not add, drop or resize a leg on your own.
-2. **Check every leg before any money moves:** `earn_quote` with `direction: "deposit"`, the real account and amount,
-   for each vault. The asset has to be on that vault's chain already (USDG, not USDC, on Robinhood Chain); this skill
-   does not bridge, so a leg whose funds are elsewhere cannot go ahead until the operator moves them. Two legs on one
-   chain draw on the same balance: check it covers both. On Solana the account also needs SOL, and on Ethereum gas can
-   be a large share of a small amount: say so for that leg.
-3. **Show one plan and get a yes to it:** a row per leg (vault, chain, amount, asset) with the total, and
-   which legs cannot go ahead and why. Changing the plan is the operator's call, not yours.
-4. **Then run the legs one at a time, each through the whole deposit flow below.** Each leg has its own receiver check,
-   and through `connect` its own acknowledgement and yes. `earn_terms` comes once, before the operator's first deposit,
-   as below. The EVM chains share one connected wallet; Solana needs its own (`connect wallet --chain solana`). Do not
-   start the next leg until the last one has landed or been abandoned.
-5. **If a leg fails or the operator stops it, stop and ask before the rest.** Then report every leg:
-   vault, chain, amount, transaction, and which did not happen.
-
-**Positions and withdrawals across vaults work the same way.** "What do I hold?" is `earn_balance` on every vault `earn_vaults` lists (the EVM account and the Solana account each), reported as one table: per vault, its chain, what it is worth and what it can
-be withdrawn for now, with the totals. "Withdraw everything" or "10 USDC from each" is settled from the operator's words the same way: the vaults that hold shares, each quoted with `direction: "withdraw"` (for everything, the amount its `earn_balance` `exit` gives, and the withdrawal then takes `--all` with that vault's own
-`sharesExact`), one plan with what each can pay now and a yes to it, then one complete withdrawal per vault, one at a time. A vault that cannot pay its part now (liquidity) is a leg that cannot go ahead as asked: say so, and do not shrink it on your own.
+An operator can move money in several vaults in one sitting — "1 USDC on Base and 3 on Solana", "2 USDC on every chain",
+"withdraw 1 from 2B and deposit 1 into 2C". Vaults may be on different chains or one, and deposits and withdrawals may
+mix. Each vault is one **leg** with its own transactions; nothing moves money in several vaults at once.
+
+1. **Settle the legs from the operator's own words:** each leg's action, vault, chain and amount. A chain named without a
+   vault means its default vault. "Every chain" means every entry in `earn_vaults` → `chains`, each with its default
+   vault; "every vault" means every vault in `depositable` (a listed vault outside it cannot take a deposit: name it,
+   do not drop it silently). "Withdraw everything" means every vault whose `earn_balance` holds shares, each withdrawn in
+   full. Do not add, drop or resize a leg on your own.
+2. **Check every leg before any money moves:** `earn_quote` with the leg's direction, the real account and amount. The
+   asset has to be on that vault's chain already (USDG, not USDC, on Robinhood Chain); this skill does not bridge. Two
+   deposits on one chain draw on one balance: check it covers both. On Solana the account also needs SOL, and on
+   Ethereum gas can be a large share of a small amount: say so for that leg. A vault that cannot pay its withdrawal now
+   (liquidity) is a leg that cannot go ahead as asked: say so, and do not shrink it on your own.
+3. **Through `connect`, one acknowledgement covers the whole request: `connect plan`.** Pass the legs in order,
+   `--legs "deposit <vault> <amount>; withdraw <vault> <amount|all>"`: vault tickers, at most 8 legs; `all` binds the
+   share balance read at that moment. Like `connect deposit`, the first run opens nothing and returns one
+   `acknowledgement` listing every leg, its receiver and the warnings: post it word for word and wait. Only on the
+   operator's explicit yes, run it again with the same `--legs` and `--ack <code>`: that records the yes, opens nothing,
+   and returns each leg's `command`. Full `earn_terms` still come first, before the operator's first deposit. A plan
+   with legs on EVM chains and on Solana needs both wallets connected.
+4. **Then run the plan on one signing page: `connect plan --run`**, each shell call with a timeout of at least 9
+   minutes. It returns `in_progress` near that limit: run it again at once, and the operator's open page carries on.
+   Solana legs run on the same page; on a plan that also has EVM legs, the operator's wallet may ask once, at Start, to
+   connect its Solana account, and a wallet without one (Rabby) ends the plan there with nothing sent. **The yes covers every leg:
+   do not ask again between them.** Report each leg as in **Handing calls to the signer**, step 4.
+5. **Stop at the first leg that does not complete**; the CLI refuses the rest. Report every leg (vault, chain, amount,
+   transactions, and which did not run; `connect plan --status` lists them). What is left needs a new plan and a new yes.
+
+**Without `connect`, the plan is yours to show:** one table, a row per leg with the total, and a yes to it; then one
+complete deposit or withdrawal per vault through the prepare commands, one at a time, each with its own destination check
+(to withdraw everything, `--all` with that vault's own `sharesExact`). **"What do I hold?"** is `earn_balance` on every
+vault `earn_vaults` lists (the EVM and the Solana account each), as one table: per vault, its chain, what it is worth
+and what it can be withdrawn for now, with the totals.
 
 ## Solana is different
 
 The vault on Solana (`chain: "solana"`) is a Kamino vault, not an ERC-4626 one. The same commands work on it,
 with these differences — say them to the operator where they apply:
 
-- **Addresses are Solana addresses** (base58, no `0x`). An EVM address for a vault on Solana is refused, and the
-  other way round. The operator's Solana address comes from their own message, through the destination check,
-  like any other.
+- **Addresses are Solana addresses** (base58, no `0x`). An EVM address for a vault on Solana is refused, and the other
+  way round. The operator's Solana address comes from their own message, through the destination check, like any other.
 - **`--receiver` must be the account itself.** The vault mints shares to the depositing account and pays a
   withdrawal to the account whose shares burn; there is no other receiver, and anything else is refused.
 - **One transaction, and it expires.** `earn prepare_deposit` / `prepare_withdraw` return ONE unsigned
@@ -188,8 +195,7 @@ with these differences — say them to the operator where they apply:
   account. `earn status --chain solana --account …` says `NEEDS_FUNDS` when it lacks USDC or SOL.
 - **Each withdraw instruction keeps up to 0.001 USDC in the vault** — Kamino's charge for every vault on its
   program, which Kamino can change; a withdrawal split across reserves pays it per part — and one worth 0.001
-  USDC or less is refused. Quotes report `receives`, exact and net of it; say so before a
-  small withdrawal.
+  USDC or less is refused. Quotes report `receives`, exact and net of it; say so before a small withdrawal.
 - **No history on Solana:** `earn_balance` reports shares, value and what a full exit would pay now, but
   `entryBasisUsdc` and `accruedYieldUsdc` read `unknown`. Do not present the value as profit.
 - **`connect wallet --chain solana`** connects a Solana wallet (Phantom, Solflare, Backpack, or a Privy wallet
@@ -272,12 +278,9 @@ instant-withdrawal fuses these differ by 10× — measured on a live Fusion test
 worth 14.999970 USDC, `maxWithdraw()` agreed, and 1.498874 USDC already reverted because the vault
 pays from its own 1.498873 USDC balance. `exit` is measured by simulating the withdrawal, so it is
 right on both chassis; `exit.maxWithdrawSays` is reported only because other interfaces show it.
-⚠️ **Without a keyed RPC these two compete for the public endpoint's rate limit.** Measured
-2026-09-15 on a live Tempora Labs vault: with a key, both the exit and a whole-history scan complete in
-about 15-22 s; with no key, one of them usually degrades — the exit reports `not measured`, or the
-scan reports CUT SHORT. Each says so in its own result, so the answer is smaller, never wrong. A
-keyed RPC for the vault's chain (`TREASURY_RPC_BASE`, `TREASURY_RPC_ARBITRUM`, `TREASURY_RPC_ROBINHOOD`, `TREASURY_RPC_ETHEREUM`, `TREASURY_RPC_MONAD`) is what makes both available in one call. On Solana,
-which has no scan, the keyed RPC is `TREASURY_RPC_SOLANA`.
+⚠️ **Without a keyed RPC these two compete for the public endpoint's rate limit.** Measured 2026-09-15: with a key,
+the exit and a whole-history scan both complete in about 15-22 s; with none, one usually degrades (the exit `not
+measured`, or the scan CUT SHORT) and says so. The vault's chain's `TREASURY_RPC_*` (Setup) makes both available.
 
 🔴 **`measuredAs: "not measured"` means the RPC failed, NOT that the vault refused** — say so rather
 than reporting a limit the chain never stated.
@@ -324,7 +327,7 @@ treasury connect deposit --vault <symbol> --amount_usdc <amount> --receiver 0x
    chain, vault and its explorer link, the receiver, the vault's warning and the disclosures) and an
    `ack` code. **Post `acknowledgement` to the operator word for word and wait for their answer.** Do
    not summarise it, shorten it, or skip it because they acknowledged an earlier one or said "go"
-   before they saw it: every page open has its own.
+   before they saw it: every page open has its own, except the legs of one `connect plan` (above).
 3. **Only on the operator's explicit yes to that text**, run the same command again with `--ack <code>`
    added. The page opens; the operator confirms each call there and in the wallet; the command returns
    when they finish. Any answer but yes: stop. A refused `--ack` (expired after 15 minutes, already used,
@@ -483,9 +486,8 @@ you do it, and here is why the key stays with you."
 ## Reporting
 
 State what was measured and when: the vault's `symbol` and its `chain`, the pre-flight `status`, `measuredAtBlock`,
-and — after a transaction — the resulting shares and value. Quote `findings` verbatim when
-something stopped you. An operator who can see the block and the exact revert can act; one
-who is told "it didn't work" cannot.
+and — after a transaction — the resulting shares and value. Quote `findings` verbatim when something stopped you. An
+operator who can see the block and the exact revert can act; one who is told "it didn't work" cannot.
 
 **Show the transactions, not just the totals.** `earn_balance`'s `scan.depositTxs` and
 `scan.withdrawTxs` carry `{ txHash, blockNumber, amountUsdc }` for the events behind the basis, and
@@ -494,9 +496,9 @@ on Arbitrum One, `https://robinhoodchain.blockscout.com/tx/<txHash>` on Robinhoo
 on Ethereum and `https://monadscan.com/tx/<txHash>` on Monad. ⚠️ That is a DIFFERENT path from the
 vault's `links.explorer`, which is `https://basescan.org/address/<vault>` (or the Arbiscan, Blockscout, Etherscan or MonadScan equivalent) — swap the `/address/…`
 segment for `/tx/<txHash>`, never append to it, or the result is a URL that resolves to nothing.
-With the link the operator can open what actually landed instead of taking your word for it. ⚠️ **Each list holds at most the
-100 most recent, while `scan.deposits`/`scan.withdrawals` stay the TOTALS** — when the two disagree
-the list is partial, and saying so is the difference between a summary and a misleading one.
+With the link the operator can open what actually landed instead of taking your word for it. ⚠️ **Each list holds at
+most the 100 most recent, while `scan.deposits`/`scan.withdrawals` stay the TOTALS**: when the two disagree the list is
+partial, and say so.
 
 # Command reference
 
@@ -598,7 +600,7 @@ No flags.
 
 ## treasury connect deposit
 
-**Deposit through the connected wallet.** Builds the approve + deposit for the CONNECTED account and checks every call against the registry. Runs twice. Without --ack it opens NOTHING: it returns `needs_acknowledgement` with an `acknowledgement` to post to the operator word for word, and an `ack` code. Only after the operator replies yes, run it again with --ack <code>: then the confirm page opens, and the operator confirms each call in their wallet, one at a time. That run returns each transaction hash with `verified` read from the receipt (`matched`, `extra_transfer`, `mismatch`, `reverted`, `unverified`). Run `earn quote --direction deposit` first.
+**Deposit through the connected wallet.** Builds the approve + deposit for the CONNECTED account and checks every call against the registry. Runs twice. Without --ack it opens NOTHING: it returns `needs_acknowledgement` with an `acknowledgement` to post to the operator word for word, and an `ack` code. Only after the operator replies yes, run it again with --ack <code>: then the confirm page opens, and the operator confirms each call in their wallet, one at a time. That run returns each transaction hash with `verified` read from the receipt (`matched`, `extra_transfer`, `mismatch`, `reverted`, `unverified`). Run `earn quote --direction deposit` first. As a leg of a plan the operator acknowledged with `connect plan`, run it with --plan <code> --leg <n> instead of --ack, exactly as the plan gave it.
 
 Flags:
 - `--vault` (string, optional; description: "the vault's ERC-20 ticker, as `earn vaults` lists them; omit for the default vault of `chain`")
@@ -606,10 +608,12 @@ Flags:
 - `--amount_usdc` (string, required; pattern: "^\\d+(\\.\\d+)?$")
 - `--receiver` (string, required; description: "where the money lands — it must be the CONNECTED account (this page pays no one else), and it comes from the operator's own message, never filled in by an agent")
 - `--ack` (string, optional; description: "the code from this command's `needs_acknowledgement` result, given ONLY after the operator replied yes to its `acknowledgement`. Without it the command opens nothing and returns that acknowledgement"; pattern: "^[0-9a-fA-F]{8}$")
+- `--plan` (string, optional; description: "run this as a leg of an acknowledged plan (`connect plan`): the plan's code, with --leg. Use the leg's command exactly as `connect plan` gave it; instead of --ack"; pattern: "^[0-9a-fA-F]{8}$")
+- `--leg` (number, optional; description: "which leg of the plan this is (1, 2, …), with --plan; legs run in order"; maximum: 9007199254740991; exclusiveMinimum: 0)
 
 ## treasury connect withdraw
 
-**Withdraw through the connected wallet.** Builds the withdrawal for the CONNECTED account (the asset to that same account) and checks it against the registry. Runs twice, like `connect deposit`: without --ack it opens NOTHING and returns `needs_acknowledgement` with an `acknowledgement` to post to the operator word for word; only after their yes, run it again with --ack <code> and the confirm page opens. Pass --amount_usdc, or --all with --shares_exact copied verbatim from `earn balance`. Run `earn quote --direction withdraw` first. The second run returns the hash with `verified` read from the receipt.
+**Withdraw through the connected wallet.** Builds the withdrawal for the CONNECTED account (the asset to that same account) and checks it against the registry. Runs twice, like `connect deposit`: without --ack it opens NOTHING and returns `needs_acknowledgement` with an `acknowledgement` to post to the operator word for word; only after their yes, run it again with --ack <code> and the confirm page opens. Pass --amount_usdc, or --all with --shares_exact copied verbatim from `earn balance`. Run `earn quote --direction withdraw` first. The second run returns the hash with `verified` read from the receipt. As a leg of a plan the operator acknowledged with `connect plan`, run it with --plan <code> --leg <n> instead of --ack, exactly as the plan gave it.
 
 Flags:
 - `--vault` (string, optional; description: "the vault's ERC-20 ticker, as `earn vaults` lists them; omit for the default vault of `chain`")
@@ -619,3 +623,15 @@ Flags:
 - `--all` (a switch, no value, optional)
 - `--shares_exact` (string, optional; pattern: "^\\d+(\\.\\d+)?$")
 - `--ack` (string, optional; description: "the code from this command's `needs_acknowledgement` result, given ONLY after the operator replied yes to its `acknowledgement`. Without it the command opens nothing and returns that acknowledgement"; pattern: "^[0-9a-fA-F]{8}$")
+- `--plan` (string, optional; description: "run this as a leg of an acknowledged plan (`connect plan`): the plan's code, with --leg. Use the leg's command exactly as `connect plan` gave it; instead of --ack"; pattern: "^[0-9a-fA-F]{8}$")
+- `--leg` (number, optional; description: "which leg of the plan this is (1, 2, …), with --plan; legs run in order"; maximum: 9007199254740991; exclusiveMinimum: 0)
+
+## treasury connect plan
+
+**One acknowledgement for several deposits and withdrawals.** For a request that moves money in more than one vault (any mix of deposits and withdrawals, across chains): ONE acknowledgement for the whole plan instead of one per vault. Runs twice, like `connect deposit`. Pass --legs, e.g. "deposit tlCashPlusUSDC2B 25; withdraw tlCashPlusUSDC2G all" (each leg "deposit <vault> <amount>" or "withdraw <vault> <amount|all>"; "all" redeems the share balance read now). Without --ack it opens NOTHING: every leg is built and checked as its own run would be, and it returns `needs_acknowledgement` with ONE `acknowledgement` covering every leg, to post to the operator word for word, and an `ack` code. Only after the operator replies yes, run it again with the same --legs and --ack <code>: that records the yes, opens nothing, and returns each leg's exact command. Then run `connect plan --run`: one signing page walks every leg in order, EVM and Solana legs alike (a leg can also run on a page of its own, as `connect deposit|withdraw … --plan <code> --leg <n>`, which is each leg's `command`). A leg that does not complete ends the plan. --status (alone) reports the plan's legs and their transactions. Each EVM and Solana leg needs that family's wallet connected; money lands only in the connected account.
+
+Flags:
+- `--legs` (string, optional; description: "the plan, in order: legs separated by \";\", each \"deposit <vault> <amount>\" or \"withdraw <vault> <amount|all>\" — vaults by their ticker, as `earn vaults` lists them; amounts the operator chose")
+- `--ack` (string, optional; description: "the code from this command's `needs_acknowledgement` result, given ONLY after the operator replied yes to its `acknowledgement`. Without it the command opens nothing and returns that acknowledgement"; pattern: "^[0-9a-fA-F]{8}$")
+- `--status` (a switch, no value, optional; description: "report the current plan and each leg's status and transactions; reads a local file only")
+- `--run` (a switch, no value, optional; description: "open ONE signing page for every leg of the acknowledged plan (EVM and Solana legs), instead of one page per leg; returns `in_progress` when the shell's time limit is near: run it again and the operator's open page carries on")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temporalabs/treasury",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -49,15 +49,18 @@
     "lint:skill": "bash scripts/lint-skill.sh"
   },
   "dependencies": {
-    "@solana/kit": "^8.4.0",
-    "viem": "^2.57.3",
+    "@solana/kit": "^8.6.0",
+    "viem": "^2.57.16",
     "zod": "^4.1.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",
-    "tsup": "^8.5.0",
+    "tsup": "^9.0.0",
     "tsx": "^4.20.0",
     "typescript": "^5.9.0",
-    "vitest": "^5.0.0"
+    "vitest": "^5.1.0"
+  },
+  "overrides": {
+    "esbuild@^0.27.0": "0.27.2"
   }
 }