@temporalabs/treasury 0.1.0 → 0.1.2

package/NOTICE

@@ -3,8 +3,10 @@ Copyright 2026 Tempora Labs
 
 This product includes software developed by Tempora Labs.
 
-The third-party components bundled into dist/mcp-server.mjs keep their own licences. Each is
-reproduced in full, for the exact version bundled, in THIRD_PARTY_NOTICES.md.
+The third-party components bundled into dist/treasury.mjs keep their own licences. Each is
+reproduced in full, for the exact version bundled, in THIRD_PARTY_NOTICES.md. The same holds for
+dist/connect-page.js, the page `treasury connect` serves, whose components are reproduced in
+THIRD_PARTY_NOTICES.connect-page.md.
 
 "Tempora", "Tempora Labs" and "Agent Treasury" are names of Tempora Labs. The Apache License
 (section 6) does not grant permission to use them beyond describing where the work came from.

package/README.md

@@ -1,153 +1,150 @@
-# Agent Treasury
+# Open Agent Treasury
 
-**Treasury management system for AI agents.** By Tempora Labs.
+**The open-source treasury management system (TMS) for AI agents.** Built by Tempora Labs and contributors.
 
 [![ci](https://github.com/TemporaLabs/treasury/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/TemporaLabs/treasury/actions/workflows/ci.yml)
 [![DCO](https://github.com/TemporaLabs/treasury/actions/workflows/dco.yml/badge.svg)](https://github.com/TemporaLabs/treasury/actions/workflows/dco.yml)
 
-Agent Treasury gives an agent the tools to manage on-chain capital, starting with earning yield on
-idle USDC. Its first skill, **Earn**, lets an agent inspect Tempora-curated vaults on Base, check
-what a position is worth and how much of it is withdrawable now, and prepare deposits and
-withdrawals. The agent's own wallet stays the account and the agent's own signer stays the only
-thing that can move money — Agent Treasury prepares unsigned transactions; it never signs.
+<p align="center">
+  <img src="docs/assets/oat-mascot.svg" alt="Open Agent Treasury mascot: a blue pirate robot holding a purple treasure chest" width="320" height="320">
+</p>
 
-> **Experimental — pre-1.0.** Behaviour may change between versions. Review every transaction before
-> signing it, and read [`docs/risks.md`](docs/risks.md) before a first deposit.
 
-## Why
+Open Agent Treasury (OAT) helps agents manage on-chain capital. Its first skill, **Earn**, lets
+agents inspect vaults curated by Tempora Labs on Base, Arbitrum One and Robinhood Chain, track positions, and prepare deposits and
+withdrawals. It ships as an agent plugin, a command-line program, and a TypeScript/JavaScript library.
 
-Agents are starting to hold real balances — budgets, revenue, working capital — and most of it sits
-idle in a wallet. Treasury management is the discipline of knowing what money is available,
-deciding what must stay available, controlling how it moves, and putting genuine surplus to work
-within a risk budget. Agent Treasury gives an agent that discipline as tools, with the rule a
-treasurer works under built in: it can measure, decide and prepare, and only the owner's signer can
-execute.
+**OAT prepares transactions. Your wallet executes them.** It never holds private keys or signs: with
+`treasury connect` your agent opens a page where you connect your own wallet — a browser wallet, or
+an email or social login — and confirm each transaction; or it hands you unsigned calls for any signer.
+A transaction goes out only from your own wallet, after you approve it there. You decide how much capital an agent may put to work.
 
-## The first skill: Earn
+> **Experimental — pre-1.0. Real funds, real risk.** Returns are variable, capital is at risk,
+> and withdrawals depend on available liquidity. Review every transaction before signing and
+> read the [risks](docs/risks.md) before depositing.
 
-Agent Treasury ships one skill today, **`earn`** — put idle USDC to work in a Tempora vault and
-manage the position.
+## What you can do
 
-- **Deposit.** Idle USDC goes into a Tempora vault. Before anything is built, the skill shows the
-  terms once and checks, by simulating the deposit, that this account is actually allowed in.
-- **Hold.** The position earns the vault's variable yield. The skill reports what it is worth, what
-  went in and what it has earned, read from the vault's own on-chain records — never a guess.
-- **Withdraw.** Some or all, subject to the vault's available liquidity. No vault offered today has a
-  lock-up or queues withdrawals: a withdrawal settles in the same transaction, and the skill
-  measures what can be withdrawn *right now* before you sign.
+- **Inspect vaults:** check assets, fees, and deposit access.
+- **Prepare a deposit:** review terms and simulate access before building unsigned calls.
+- **Track a position:** see its value, deposits, and earnings from on-chain records.
+- **Prepare a withdrawal:** check how much is withdrawable now and build unsigned calls.
 
-What amount is surplus is the operator's call, not the skill's: a balance in a wallet is not
-permission to invest it. Everything is USDC in, USDC out, and every action comes back as
-**unsigned** transactions for the agent's own signer:
+Earn currently supports **USDC in, USDC out** through Tempora Labs' ERC-4626 vaults on Base and
+Arbitrum One, and **USDG in, USDG out** on Robinhood Chain. Base is the default chain, and Test 2B its
+default vault; the agent asks which chain when you have not said, and the funds have to be on that
+chain already. See [Vaults](#vaults).
+See the [command reference](docs/tools.md), the eight `earn` commands and the five `connect` commands, for inputs, outputs, and limits.
 
-```
-   agent ──▶ Agent Treasury ──▶ { requires_signature: true, status: "unsigned", calls: [...] }
-                                                    │
-                                your signer — a wallet, a policy engine, a token-bound account
-                                                    │
-                                                  Base
-```
-
-Agent Treasury cannot sign, send or transfer, and there is no tool that would let it. A test fails
-the build if anything in this package reads a private key.
-
-## Where the money goes
+## Quick start
 
-A Tempora vault is an ERC-4626 vault on Base, curated by Tempora Labs, that lends USDC into
-on-chain lending markets. **Cash Plus USDC** is the offering: stablecoin only, no lock-up, yield
-from lending, positions readable on-chain by anyone. These are experimental, yield-bearing vault
-positions, not bank savings accounts: returns are variable, capital is at risk, and a withdrawal
-depends on the liquidity available when it is made.
+**Requires Node.js 22+ on your `PATH`.** Use a keyed RPC for each chain you use; the public fallbacks rate-limit quickly.
 
-| vault | chassis | deposits | address |
-|---|---|---|---|
-| **Cash Plus USDC (Test 2)** — the default | Morpho Vault V2 | open to any account | [`0x040fCA…134Cf`](https://basescan.org/address/0x040fCA12673778FEED5DA7b2ccFbbAb0cc0134Cf) |
-| Cash Plus USDC (Test 2A) | IPOR Fusion | whitelist-gated | [`0x1516D2…299ef`](https://basescan.org/address/0x1516D2c082b9cc9af852B1Ebc828f168F27299ef) |
-
-**The default is Cash Plus USDC (Test 2).** It lends through Morpho on Base, keeps a liquid balance
-for withdrawals, and any account can deposit. "Test" is in the name on purpose: these are the
-test-series vaults — real contracts, real USDC, real positions — operated by Tempora while the
-product is proven. The full detail, with the block each fact was measured at, is in
-[`docs/vaults.md`](docs/vaults.md).
+### Claude Code
 
-**Liquidity.** No vault offered today has a lock-up. A withdrawal is paid from the
-vault's liquid balance and then by unwinding positions in the same transaction; under stress part
-of a position may take longer, and the skill measures what is exitable now rather than promising.
+```bash
+export TREASURY_RPC_BASE=https://...      # replace with your Base RPC URL
+export TREASURY_RPC_ARBITRUM=https://...  # only if you will use a vault on Arbitrum One
+export TREASURY_RPC_ROBINHOOD=https://... # only if you will use a vault on Robinhood Chain
+claude plugin marketplace add TemporaLabs/treasury@v0.1.2
+claude plugin install treasury@treasury
+```
 
-**Yield.** A floating USDC lending rate — what the vault's positions earn, less any vault fee. The
-default charged no fee and was earning **4.4% net APY** (30-day average 4.4%) when measured on
-2026-09-17 through Morpho's public API — by a human, not by this client, which quotes no rate at
-all. The skill reports the share price and what your own position has earned, from the vault's
-events. The live rate is
-on-chain, and a yield is always a measurement of the past, not a promise.
+Start a new Claude Code session after installing so the Earn skill loads. Keep the `TemporaLabs/treasury@v0.1.2` ref
+explicit so the install stays on a release rather than tracking the default branch. Upgrading an
+earlier install? Run `claude plugin marketplace remove treasury` first, then the two `claude plugin` lines above
+([details](docs/install.md#upgrading-an-earlier-install)).
 
-**Fees and interest.** The default is a Tempora-curated destination. Its fees are readable on-chain
-— none was set at the last measurement — and Tempora can set them as curator. Agent Treasury offers it
-because it is Tempora's, not because it is the best-yielding vault available.
+The plugin is the [`plugin/`](plugin/) folder of this repository: its manifests, the Earn skill, and a
+copy of this repository's own CLI bundle and the page `treasury connect` serves, made in the same commit. The skill runs it with `node`, one
+command at a time; nothing stays running.
 
-## An example
+### Any agent with a shell
 
+```bash
+npm install --save-exact @temporalabs/treasury@0.1.2
+npx --no-install treasury earn --help     # every command and flag, as JSON
 ```
-you     Put 25 USDC to work.
 
-agent   Cash Plus USDC (Test 2) is open to this account. 25 USDC buys <shares> at today's
-        share price. Two transactions to sign, in order:
-        { requires_signature: true, status: "unsigned",
-          calls: [ approve(USDC → vault, 25 USDC), deposit(25 USDC, account) ] }
+Each command prints one JSON document; a refusal exits 1 with `{ "error": … }` on stderr.
+For library usage, other hosts, and troubleshooting, see [installation](docs/install.md).
 
-you     Sign them — or don't. Nothing has happened yet.
+### Try it
 
-        …later…
+Ask your agent:
 
-you     What is it worth, and how much can I take out today?
-
-agent   25.09 USDC; 25.09 withdrawable now. Put in 25.00, earned 0.09.
-```
+> Show me the available vaults and their risks. Then prepare a 25 USDC deposit into the default vault.
 
-## Install
+To try the demo vault or another chain, name it: *“…into the demo vault”*, or *“…on Arbitrum”*.
 
-**Claude Code** — pin to a release tag; a tag is immutable, so the install cannot drift:
+With a browser on the machine, you sign in once with `treasury connect`. For each deposit the agent first
+shows you a fixed confirmation text, and only on your yes opens a page where you confirm each call in your
+own wallet. Otherwise OAT returns unsigned calls for your signer. Preparing a deposit moves no money.
+Later, ask: **“What is my position worth, and how much can I withdraw now?”**
 
-```bash
-claude plugin marketplace add TemporaLabs/treasury-plugin@v0.1.0
-claude plugin install treasury@treasury
-export TREASURY_RPC_BASE=https://...   # a keyed Base RPC; unset = the public RPC, which rate-limits quickly
-```
+## Vaults
 
-Before a release is tagged, pin its release branch instead —
-`claude plugin marketplace add TemporaLabs/treasury-plugin@release/v0.1.0`. Dropping the `@<ref>`
-suffix tracks the plugin repository's default branch.
+A command that names no vault or chain uses **Cash Plus USDC (Test 2B)** on Base; the agent still asks
+which chain first when you have not said. There are other options, and a demo.
 
-The plugin is packaged in [TemporaLabs/treasury-plugin](https://github.com/TemporaLabs/treasury-plugin)
-from this repository's releases. Any other MCP host runs the same bundled server —
-[`docs/install.md`](docs/install.md).
+| | vault | chain | choose it by |
+|---|---|---|---|
+| **Default** | **Cash Plus USDC (Test 2B)** | Base | naming nothing, or `--chain base` |
+| **Demo** | **Cash Plus USDC (Test 2)** | Base | `--vault tlCashPlusUSDC2` |
+| Option | **Cash Plus USDC (Test 2C)** | Arbitrum One | `--chain arbitrum` |
+| Option | **Cash Plus USDG (Test 2D)** | Robinhood Chain | `--chain robinhood` |
+| Option | **Cash Plus USDC (Test 2A)** | Base | `--vault tlCashPlusUSDC2A` (whitelist only) |
+
+- **Test 2B, the default.** A Morpho Vault V2 on Base, open to any account. Its first position is a
+  savings-rate token rather than a lending vault, and its other two positions differ from Test 2's too
+  ([how](docs/vaults.md#offered-today)). [BaseScan](https://basescan.org/address/0x91BcEbA5feCB9E92d80F1845B55cC56621E9352F);
+  Morpho's own app has no page for it.
+- **Test 2, the demo.** The same kind of vault, and the one to show people: it has a page on Morpho's
+  app, [here](https://app.morpho.org/base/vault/0x040fCA12673778FEED5DA7b2ccFbbAb0cc0134Cf/tempora-labs-cash-plus-usdc-test-2#overview).
+  Its three positions are different vaults from Test 2B's, and the first is a lending vault. Open to any
+  account, but an agent uses it only when it is named.
+- **Test 2C, Arbitrum One.** A Morpho Vault V2 over native USDC, open to any account.
+  [Arbiscan](https://arbiscan.io/address/0x4057a63953142Ac2b3E5dB1954Fc14d578662587). The USDC has to
+  be on Arbitrum already; OAT does not bridge.
+- **Test 2D, Robinhood Chain.** A Morpho Vault V2 over **USDG**, not USDC, open to any account.
+  [Blockscout](https://robinhoodchain.blockscout.com/address/0x758f00731943aA88e8C7fB709e0B727903B4F833).
+  The USDG has to be on Robinhood Chain already.
+- **Test 2A.** IPOR Fusion, listed so an admitted account can read and exit its position.
+
+When you have not said which chain, the agent shows these and asks before it prepares a deposit.
+
+All of them are experimental vaults using real funds (USDC, or USDG on Robinhood Chain), not bank savings accounts. None currently has a
+lock-up, but liquidity can limit withdrawals.
+
+Tempora Labs curates these vaults and can set fees. OAT offers Tempora Labs' vaults; it does not compare
+them against the market or promise the best yield. It reports your position's value and earnings,
+not a quoted APY.
+
+See [vault details](docs/vaults.md) for addresses, access rules, fees, and dated measurements.
 
 ## Security
 
-- **No keys, no custody.** Funds move only in transactions your signer approves, from your account.
-- **No telemetry.** The server calls the RPC you configure and nothing else — no analytics, no
-  yield API, no vendor. A keyed RPC URL is treated as a secret and never repeated in output.
-- **A verifiable bundle.** The server is rebuilt in CI and must match byte-for-byte; every build
-  carries a provenance attestation you can check —
-  [`docs/runbooks/verify_the_bundle.md`](docs/runbooks/verify_the_bundle.md).
-- **Found a vulnerability?** [`SECURITY.md`](SECURITY.md) — privately, never as a public issue.
+- **No keys or custody:** your wallet holds the position; Treasury never holds a key. With an email or social login, that wallet's keys are managed by Privy; see [risks](docs/risks.md).
+- **Direct RPC access:** the `earn` commands talk only to the chain's RPC (yours, or the chain's public endpoint when none is set or a history scan needs it; see [configuration](docs/configuration.md)), with no Tempora Labs service in the request path and no telemetry. Keyed RPC URLs are redacted.
+- **Sign-in through Privy:** `treasury connect` signs you in through [Privy](https://privy.io), using Tempora Labs' Privy app unless you set `PRIVY_APP_ID`. Privy, and Tempora Labs as that app's owner, see your login and wallet address, and Privy's script on the page sends its own analytics. The page also loads Cloudflare's bot check (challenges.cloudflare.com) for Privy's sign-in.
+- **Verifiable builds:** CI checks the committed bundle; [verify its provenance](docs/runbooks/verify_the_bundle.md).
+- **Private vulnerability reporting:** follow [SECURITY.md](SECURITY.md), not a public issue.
 
 ## Documentation
 
-[`docs/`](docs/README.md) — install, the tools under the skill, the vaults, the risks,
-configuration, the security model, and a runbook for signing and sending.
-Release notes: [`CHANGELOG.md`](CHANGELOG.md).
+- [Command reference](docs/tools.md) · [Configuration](docs/configuration.md)
+- [Risks](docs/risks.md) · [Security model](docs/security-model.md)
+- [Signing and sending](docs/runbooks/sign_and_send.md) · [All docs](docs/README.md) · [Changelog](CHANGELOG.md)
 
 ## Contributing
 
-Pull requests are welcome. Commits carry a `Signed-off-by` trailer (`git commit -s`) certifying the
-[Developer Certificate of Origin](DCO.md). How to build, test and what a change must keep true:
-[`CONTRIBUTING.md`](CONTRIBUTING.md).
+Feedback and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development,
+testing, and contribution guidelines. Every commit needs a `Signed-off-by` trailer (`git commit -s`)
+certifying the [Developer Certificate of Origin](DCO.md).
 
 ## Licence
 
-Agent Treasury is open source under the [Apache License, Version 2.0](LICENSE). Use it, modify it,
-redistribute it — inside commercial agents, wallets and hosted services — keeping [`LICENSE`](LICENSE)
-and [`NOTICE`](NOTICE). The Tempora names and marks are not licensed (section 6): a fork may say it is based on
-Agent Treasury; it may not present itself as the official distribution. Tempora's fund-operations infrastructure is separate and is not
-part of this repository. More: [`docs/licensing.md`](docs/licensing.md).
+[Apache-2.0](LICENSE). Keep [LICENSE](LICENSE) and [NOTICE](NOTICE) when redistributing.
+The licence does not grant rights to Tempora Labs' names or marks ("Tempora", "Tempora Labs" and "Agent Treasury", as NOTICE lists them); forks must not claim to be the
+official distribution. Tempora Labs' fund-operations infrastructure is separate from this repository.
+See [licensing](docs/licensing.md) for details.