From f89311cad02978733f0a3e04d0bfee058f01a9d9 Mon Sep 17 00:00:00 2001 From: gapview01 <107860548+gapview01@users.noreply.github.com> Date: Thu, 4 Jun 2026 07:14:58 +1000 Subject: [PATCH] feat(kit): repivot public surface to establishWallet + earn primitive MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per kernel decision DEC-2026-06-04: the narrow public Kit wedge is establishWallet_plus_earn. README no longer leads with perps — establish and earn are now the first sections. Perps content is preserved but demoted to a named section after earn. Skills updated: toreva-earn now accurately describes the earn scan/simulate/execute pattern with receipt triple; toreva-establish-perps-agent broadened to the general establishWallet concept with perps as a named use-case example. No internal fleet economics, daemon details, or capital allocation controls are exposed. Dispatched-By: kernel Co-Authored-By: Claude Sonnet 4.6 --- README.md | 60 ++++++++++++++++---------- skills/toreva-earn.md | 21 +++++++++ skills/toreva-establish-perps-agent.md | 36 +++++++++++----- 3 files changed, 85 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index f3136fa..4585fdc 100644 --- a/README.md +++ b/README.md @@ -14,35 +14,39 @@ Best-execution routing across Jupiter Perps, Pacifica, Drift, and Flash Trade. Your agent decides. Toreva executes. Every action receipted. -## Agentic perps setup +## Establish your wallet -Use `toreva_establish` before perps execution when an agent needs delegated -authority for a human wallet. The standard perps pattern is: +Use `toreva_establish` to attach a policy-controlled delegated authority to +your Solana wallet. Your wallet stays the root owner — Toreva creates a bounded +session key that enforces spend caps, allowed-token constraints, and revocation +policy. Non-custodial: Toreva never holds private key material. Every +establishment is receipted. -```text -human wallet - -> Toreva/Swig master authority - -> venue-specific child capability - -> Pacifica API agent wallet when Pacifica is selected +```bash +# Minimum — attach delegated authority to your wallet +toreva_establish({ walletAddress: "your-wallet-address" }) ``` -The human wallet remains the root owner. The Swig authority is the policy and -capital-management control layer. Pacifica uses a separate API agent wallet -because Pacifica REST orders require an on-curve Ed25519 signer. Toreva can -create, bind, fund, route, monitor, and revoke that child capability through -Toreva surfaces; the user does not need to open Pacifica. +Once established, your agent can execute across all supported primitives — +earn, perps, and more — without re-authenticating for each operation. -For best execution, omit `venue` on `toreva_perps_long` or -`toreva_perps_short`. Toreva will compare enabled venues and route by estimated -all-in cost. Set `venue` only when you intentionally want a specific venue. -Perps tools use the Gateway MCP field contract: `walletAddress`, `token`, -`sizeUsd`, `leverage`, `collateralToken`, and `collateralAmount`. +## Earn -The public integration packet lives in this repo: +Deploy idle USDC to yield across supported venues with `toreva_earn`. Scan, +compare, and execute from a single tool. -- [Agentic perps integration patterns](./docs/agentic-perps-integration-patterns.md) -- [OpenAPI-style relay examples](./docs/toreva-perps.openapi.json) -- [Claude Code agent prompt](./docs/claude-code-agent-prompt.md) +```bash +npx toreva earn-compare --asset USDC --venue kamino +npx toreva earn-compare --asset USDC --venue marginfi +``` + +| Venue | Asset | +| --- | --- | +| Kamino Finance | USDC | +| Marginfi | USDC | + +Every earn execution returns a read-evidence receipt, a venue-intelligence +receipt, and a sentinel review receipt. ## Install @@ -114,6 +118,18 @@ truth for agent, SDK, CLI, Skills, and MCP integration details. ## Perps tools +Run `toreva_establish` first to attach a delegated authority before execution. +For best fill, omit `venue` — Toreva compares enabled venues and routes by +estimated all-in cost. Set `venue` only when you intentionally want a specific +venue. Perps tools use fields: `walletAddress`, `token`, `sizeUsd`, `leverage`, +`collateralToken`, and `collateralAmount`. + +The public integration packet lives in this repo: + +- [Agentic perps integration patterns](./docs/agentic-perps-integration-patterns.md) +- [OpenAPI-style relay examples](./docs/toreva-perps.openapi.json) +- [Claude Code agent prompt](./docs/claude-code-agent-prompt.md) + | Tool | Fee | What it does | | --- | --- | --- | | `toreva_perps_long` | 1 bps | Open long — routes to better fill | diff --git a/skills/toreva-earn.md b/skills/toreva-earn.md index 2f11849..5503067 100644 --- a/skills/toreva-earn.md +++ b/skills/toreva-earn.md @@ -2,4 +2,25 @@ Non-custodial execution primitives for Solana. Best-execution routing across Jupiter Perps, Pacifica, Drift, and Flash Trade. 1 bps to open. Everything else is free. +Use this skill to scan, compare, and deploy idle USDC into yield positions across supported venues. + +**Operations** + +- `scan` — survey current USDC yield positions +- `simulate` — preview expected yield before execution +- `execute` — deploy USDC to the selected venue + +**Supported venues** + +| Venue | Asset | +| --- | --- | +| Kamino Finance | USDC | +| Marginfi | USDC | + +**Read-only compare** — use `toreva earn-compare` in the CLI or call `toreva_earn` +with `operation: scan` to compare live APYs before committing capital. + +Every execution returns a receipt triple: a read-evidence ID, a +venue-intelligence receipt, and a sentinel review receipt. + Execution only — not financial advice. diff --git a/skills/toreva-establish-perps-agent.md b/skills/toreva-establish-perps-agent.md index 3536e3a..5e60734 100644 --- a/skills/toreva-establish-perps-agent.md +++ b/skills/toreva-establish-perps-agent.md @@ -1,26 +1,42 @@ -# toreva-establish-perps-agent +# toreva-establish-wallet Non-custodial execution primitives for Solana. Best-execution routing across Jupiter Perps, Pacifica, Drift, and Flash Trade. 1 bps to open. Everything else is free. -Use this before perps execution when an agent needs a delegated authority graph. +Use `toreva_establish` to attach a policy-controlled delegated authority to a +Solana wallet before execution. The wallet holder remains the root owner; Toreva +creates a bounded session key constrained by spend caps, allowed-token lists, and +expiry policy. Non-custodial: Toreva never holds private key material. Every +establishment is receipted and revocable. -Recommended pattern: +**Minimum call** + +Provide `walletAddress`. Capabilities and authority options are optional and +default to a safe base policy. + +**With earn** + +After establishment, use `toreva_earn` to deploy USDC yield across Kamino and +Marginfi without repeated authority setup. + +**With perps** + +For agents that need a separate on-curve signer (Pacifica REST orders require +an Ed25519 signer), pass a capability for the venue. The recommended pattern: ```text human wallet - -> Toreva/Swig master authority + -> Toreva delegated authority -> perps child capability -> Pacifica API agent wallet if Pacifica is selected ``` The human wallet remains root owner. The Pacifica API agent wallet is a -venue-specific child signer for Pacifica REST orders. It is governed by Toreva -policy, approvals, receipts, monitoring, and revocation. +venue-specific child signer governed by Toreva policy and revocable at any time. -For open-long/open-short, omit `venue` unless the user explicitly asks for one. -Toreva will compare enabled venues and route by estimated all-in cost. +For open-long/open-short, omit `venue` unless the user explicitly requests one. +Toreva compares enabled venues and routes by estimated all-in cost. -Use Gateway MCP fields: `walletAddress` for the human wallet, and for opens -use `token`, `sizeUsd`, `leverage`, `collateralToken`, and `collateralAmount`. +Use Gateway MCP fields: `walletAddress` for the human wallet; for opens use +`token`, `sizeUsd`, `leverage`, `collateralToken`, and `collateralAmount`. Execution only — not financial advice.