morpho-vault-manager 0.1.0

package/ARCHITECTURE.md

@@ -0,0 +1,179 @@
+# Architecture
+
+## Purpose
+
+This repository will produce a native OpenClaw plugin that onboards a user into a constrained Morpho vault-management agent and runs that agent periodically through OpenClaw cron.
+
+The architecture is intentionally narrow. The system is not a general trading bot and not a generic DeFi wallet manager.
+
+## System Boundaries
+
+### In Scope
+
+- Native OpenClaw plugin packaging
+- `configure` onboarding flow with `clack`
+- OWS wallet creation/import and API-key provisioning
+- Morpho data reads and transaction preparation
+- Periodic rebalancing through OpenClaw cron
+- Reporting and auditability
+
+### Out of Scope for v1
+
+- Cross-chain bridging
+- Swaps
+- Borrowing strategies
+- Leverage
+- Arbitrary smart-contract execution
+- Custom OpenClaw agent harness runtime
+
+## Major Components
+
+### 1. OpenClaw Native Plugin
+
+Responsibilities:
+
+- expose CLI/setup entrypoints
+- own plugin config and profile storage
+- create/update the dedicated OpenClaw agent
+- write standing instructions into the agent workspace
+- create and manage cron jobs
+- discover or persist per-profile cron delivery targets
+
+### 2. OpenClaw Agent Runtime
+
+Responsibilities:
+
+- execute the periodic rebalance turn
+- use the vendored Morpho skill guidance
+- call local script entrypoints and future plugin tools
+- report results through OpenClaw task and cron surfaces
+
+This repo assumes the standard OpenClaw agent runtime. The plugin does not own session compaction, thread lifecycle, or model transport.
+
+### 3. OWS
+
+Responsibilities:
+
+- wallet lifecycle
+- API-key based agent access
+- API-key provisioning may remain manual/out-of-process in v1 to keep the raw token out of plugin process memory
+- signing
+- future `signAndSend` support when a documented CLI surface exists
+
+Current integration mode is local subprocess access. The current live wrapper signs through `ows sign tx` and then broadcasts through Base RPC because the documented OWS CLI reference does not currently document a `signAndSend` command. Future direct SDK or local daemon integration is optional.
+
+### 4. Morpho Tooling
+
+Responsibilities:
+
+- read Morpho vault and position state
+- prepare unsigned transactions
+- simulate transactions before execution
+
+The rebalance runtime uses `morpho-cli` directly. Morpho skill content is installed as a workspace skill from [`morpho-org/morpho-skills`](https://github.com/morpho-org/morpho-skills/) so agents have Morpho-specific operating instructions available via the skill system.
+
+## End-to-End Flow
+
+### Configure
+
+1. User runs `openclaw vault-manager configure`.
+2. Plugin checks for required tools and daemon assumptions.
+3. Plugin creates or imports an OWS wallet.
+4. Plugin emits OWS API-key provisioning instructions, and the operator completes token creation out-of-process so the raw token never enters plugin process memory.
+6. Plugin records the risk profile.
+7. Plugin offers funding guidance and an optional "continue once funded" balance poll against Morpho token reads.
+8. Plugin offers optional model-routing preference for the dedicated agent.
+9. Plugin creates a dedicated OpenClaw agent workspace.
+10. Plugin writes `AGENTS.md` standing orders into that workspace.
+11. Plugin configures cron delivery for that profile: default `channel=last`, or an explicit Telegram target discovered from OpenClaw directory surfaces.
+12. Plugin creates an isolated OpenClaw cron job for periodic execution.
+13. Plugin runs a final validation plan against live Morpho state and persists the outcome in the profile.
+
+### Rebalance Run
+
+1. OpenClaw cron wakes the dedicated agent in an isolated session.
+2. The agent calls `openclaw vault-manager plan` to get a deterministic allocation plan (vault scoring, target allocations, actions).
+3. If the plan status is `no_op` or `blocked`, the agent reports reasons and stops.
+4. If the plan status is `planned`, the agent executes each action:
+   a. Prepares transactions using morpho-cli (`morpho prepare-deposit` or `morpho prepare-withdraw`).
+   b. Verifies simulation success. Stops on first failure.
+   c. Signs the prepared transaction using OWS (`ows sign tx`).
+   d. Broadcasts the signed transaction to the Base network.
+   e. Waits for transaction confirmation.
+5. The agent reports all executed transactions (hashes, gas) or failure reasons.
+
+## Repository Structure Targets
+
+This is the intended direction for the repo:
+
+```text
+.
+├── AGENTS.md
+├── ARCHITECTURE.md
+├── SECURITY.md
+├── docs/
+│   ├── openclaw-vault-manager-spec.md
+│   └── exec-plans/
+│       └── active/
+├── evals/
+├── scripts/
+│   ├── check/
+│   ├── dev/
+│   └── rebalance/
+└── src/
+    └── plugin implementation
+```
+
+`src/` now contains the native plugin, CLI surfaces, and the first rebalance runtime implementation.
+
+## Invariants
+
+- The plugin must remain model-agnostic.
+- All live writes must be signed through OWS.
+- Base-only and USDC-only must be enforceable mechanically, not just mentioned in prompts.
+- The rebalance runtime must only forward `morpho-cli`-prepared transactions to OWS. Agent-authored calldata never reaches signing.
+- Simulation failure is terminal for a run.
+- Live execution must be auditable from logs and evals.
+
+## Required Future Modules
+
+### Config/Profile Layer
+
+- profile file loading
+- risk profile resolution
+
+### OWS Adapter
+
+- wallet lookup
+- API key management
+- sign wrapper plus broadcast/receipt verification
+
+### Morpho Adapter
+
+- vault discovery
+- position reads
+- transaction preparation
+- simulation handling
+
+### Rebalance Engine
+
+- weighted scoring: `apy_weight * net_apy + tvl_weight * normalized_tvl - fee_weight * fee_pct - rewards_penalty`
+- per-profile score weights and reward preference
+- target weight computation
+- drift detection
+- execution plan generation
+
+### OpenClaw Adapter
+
+- agent bootstrap
+- workspace file generation
+- cron management
+- delivery-target discovery (`channels list`, `directory groups list`)
+- reporting hooks
+
+## Design Bias
+
+- Prefer explicit adapters over direct shell calls spread across the codebase.
+- Prefer deterministic scripts over undocumented shell recipes.
+- Prefer narrow data contracts over implicit object blobs.
+- Prefer a few hard constraints over a large prompt.

package/README.md

@@ -0,0 +1,68 @@
+# Morpho Vault Manager
+
+Native OpenClaw plugin for onboarding and running a constrained Morpho vault manager agent on Base.
+
+## Scope
+
+- Base only
+- USDC only
+- Morpho vault management only
+- All signing through OWS
+
+## Prerequisites
+
+- `openclaw` installed and the gateway running
+- OpenClaw gateway `2026.4.12` or newer
+- `ows` installed and on `PATH`
+- `bunx @morpho-org/cli` available
+- A Base RPC URL configured if you plan to exercise live broadcast verification
+
+## Install
+
+```bash
+openclaw plugins install morpho-vault-manager
+openclaw plugins enable morpho-vault-manager
+openclaw gateway restart
+```
+
+## Configure
+
+```bash
+openclaw vault-manager configure
+```
+
+The configure flow will:
+
+1. run preflight checks
+2. guide wallet create/import through OWS
+3. ask you to create the OWS API key in a separate shell
+4. record the token source as an env var or file reference
+5. generate the dedicated agent workspace and `AGENTS.md`
+6. choose how cron results are delivered (`last` route by default, or a pinned target)
+7. create the OpenClaw cron job
+8. run a final validation plan
+
+The plugin never stores owner credentials or raw private keys in repo files, prompts, or profile JSON.
+
+## Verify
+
+```bash
+openclaw vault-manager status
+openclaw vault-manager plan --json
+openclaw vault-manager run-now
+```
+
+Release QA should include operating the installed plugin through `openclaw` directly, not just running repo-local checks.
+
+For repository-level health checks before publishing:
+
+```bash
+scripts/dev/doctor --format=json
+scripts/check/publish
+scripts/check/release-install
+```
+
+## Release QA
+
+Use [docs/release-qa-checklist.md](docs/release-qa-checklist.md) as the final pre-release verification sheet for publish, install, configure, cron, and safety checks.
+`scripts/check/release-install` is the fail-closed release gate for packed-artifact install on a supported OpenClaw version.

package/SECURITY.md

@@ -0,0 +1,103 @@
+# Security
+
+## Security Goal
+
+The system must let an agent manage a constrained Morpho vault portfolio without ever granting that agent unconstrained wallet access.
+
+## Primary Threat Model
+
+We assume:
+
+- the model may hallucinate or choose an unsafe action
+- the local machine is trusted enough to run OpenClaw and OWS, but the agent should still operate under least privilege
+
+We do not assume the prompt alone will prevent unsafe execution.
+
+## Non-Negotiable Invariants
+
+- Owner credentials never enter agent-visible runtime state.
+- Raw private keys never appear in plugin code, logs, prompts, config, or repo files.
+- The agent receives only an OWS API token.
+- The rebalance runtime only forwards transactions produced by `morpho-cli` prepare flows to OWS. No code path accepts agent-authored calldata.
+- Live execution is allowed only on Base for v1.
+- Live execution is allowed only for USDC Morpho vault operations for v1.
+- All live signatures must come from OWS.
+- Simulation failure aborts execution.
+
+## Credential Model
+
+### Owner Credential
+
+- Full wallet authority
+- Must never be used by the periodic vault-manager agent
+
+### OWS API Token
+
+- Scoped to one wallet for v1
+- The only credential the agent may use
+- In v1, the raw token is provisioned out-of-process so the plugin never needs to load it into process memory
+
+### Broadcast Path
+
+- Current implementation uses OWS for signing and Base RPC for broadcast plus receipt verification.
+- This does not widen secret access: the signing boundary remains inside OWS.
+- When the OWS CLI exposes a documented `signAndSend` surface, the plugin should move broadcast into OWS as well.
+
+## OWS Policy Model
+
+The plugin does not create, attach, or enforce custom OWS policies.
+
+OWS default policy behavior is left untouched. The plugin's enforcement point is the runtime path around OWS:
+
+- only `morpho-cli` prepare flows may produce transactions for signing
+- no code path accepts agent-authored calldata and hands it to OWS
+- Base-only, USDC-only, turnover, and simulation constraints are enforced in the plugin runtime before signing
+
+If a future change allows calldata to reach OWS through any path other than Morpho prepare output, the trust model must be re-evaluated and documented before merge.
+
+## Morpho Skill
+
+Morpho protocol interaction is provided via the `morpho-cli` workspace skill (from [`morpho-org/morpho-skills`](https://github.com/morpho-org/morpho-skills/)). The skill provides CLI-based query and prepare commands that return unsigned transactions. The rebalance runtime uses `morpho-cli` directly and runs under the narrow AGENTS.md contract.
+
+## Logging Rules
+
+- Do not log owner credentials, API tokens, private keys, mnemonics, or raw decrypted secret material.
+- If logging command lines, redact secrets and token-like strings.
+- If logging transaction plans, prefer summarized transaction metadata over full sensitive payload dumps unless debugging is explicitly enabled.
+
+## Storage Rules
+
+- Do not commit secrets to the repo.
+- Do not write owner credentials into OpenClaw prompts or workspace files.
+- API tokens must be resolved through the configured token source (`env` or `file`), never hardcoded in profile JSON or plugin config.
+- `file` sources are intended for mounted-secret setups (Docker/k8s/systemd EnvironmentFile). File contents are read at execution time and never copied into the profile.
+- Profile files may contain public addresses, wallet IDs, thresholds, cron metadata, delivery targets/account ids, and the token source descriptor (kind + identifier), never the token value itself.
+- The configure flow should emit the OWS API-key provisioning command and then accept only the resulting token source descriptor, not the raw token.
+
+## Cron Delivery
+
+- Cron delivery routing is public operational metadata, not secret material.
+- A profile may store `deliveryChannel`, `deliveryTo`, and `deliveryAccountId` so each managed agent can announce to a different chat destination.
+- The default delivery route should be OpenClaw's `last` channel target unless the operator pins an explicit destination.
+- Discovery of Telegram groups/topics should use OpenClaw CLI directory surfaces only; the plugin must not scrape or persist unrelated chat history to infer a target.
+
+## Execution Guardrails
+
+- Configure flows should run a validation plan before completing onboarding.
+- Transaction preparation and execution is delegated to the agent using morpho-cli and OWS. The agent's AGENTS.md instructions enforce:
+  - Only morpho-cli-prepared transactions reach OWS signing (no agent-authored calldata).
+  - Simulation failure is terminal — the agent must stop on first failure.
+  - Chain (Base) and asset (USDC) scope are enforced by the plan command's scoring engine.
+  - The agent must report transaction hashes and verification details after each run.
+
+## Review Checklist
+
+Every write-path change should be reviewed against these questions:
+
+1. Does any new code handle sensitive material directly?
+2. Can this path produce a live transaction after a failed simulation?
+3. Can this path forward calldata to OWS that did not come from a `morpho-cli` prepare flow?
+4. Can this path operate on a non-Base chain or non-USDC asset?
+5. Is the failure mode explicit and visible to the operator?
+
+If any answer is "yes", the change is blocked until the architecture and security docs are updated and the guardrail is encoded mechanically.

package/dist/index.js

@@ -0,0 +1,43 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { normalizeResolvedSecretInputString } from "openclaw/plugin-sdk/secret-input";
+import { registerVaultManagerCli } from "./src/cli/register.js";
+import { registerInlineToken } from "./src/lib/secrets.js";
+import { resolveVaultManagerSettings } from "./src/lib/settings.js";
+export default definePluginEntry({
+    id: "morpho-vault-manager",
+    name: "Morpho Vault Manager",
+    description: "Onboard and operate a constrained Morpho vault manager agent on OpenClaw.",
+    register(api) {
+        const pluginConfig = (api.pluginConfig ?? {});
+        try {
+            const resolved = normalizeResolvedSecretInputString({
+                value: pluginConfig.apiKey,
+                refValue: pluginConfig.apiKeyValue,
+                path: "plugins.entries.morpho-vault-manager.apiKey"
+            });
+            if (resolved) {
+                registerInlineToken("plugin-config:apiKey", resolved);
+                pluginConfig.apiKeyValue = resolved;
+            }
+        }
+        catch (error) {
+            api.logger?.warn?.(`morpho-vault-manager: unresolved SecretRef for apiKey — ${error.message}`);
+        }
+        const settings = resolveVaultManagerSettings(pluginConfig);
+        api.registerCli(({ program, logger }) => {
+            registerVaultManagerCli({
+                program,
+                logger,
+                settings
+            });
+        }, {
+            descriptors: [
+                {
+                    name: "vault-manager",
+                    description: "Configure and operate the Morpho vault manager agent",
+                    hasSubcommands: true
+                }
+            ]
+        });
+    }
+});

package/dist/src/bin/rebalance.js

@@ -0,0 +1,26 @@
+function parseArgs(argv) {
+    let profileId = "default";
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--profile") {
+            profileId = argv[index + 1] ?? profileId;
+            index += 1;
+        }
+    }
+    return { profileId };
+}
+async function main() {
+    const { profileId } = parseArgs(process.argv.slice(2));
+    const [{ runPlan }, { resolveVaultManagerSettings }] = await Promise.all([
+        import(new URL("../lib/rebalance.ts", import.meta.url).href),
+        import(new URL("../lib/settings.ts", import.meta.url).href)
+    ]);
+    const settings = resolveVaultManagerSettings();
+    const result = await runPlan(settings, profileId);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+main().catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+});
+export {};