@juanscilingo/vaults-cli 0.1.1-alpha.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +140 -0
- package/dist/cli.mjs +22392 -0
- package/package.json +26 -0
- package/skills/smart-yield/SKILL.md +83 -0
package/package.json
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@juanscilingo/vaults-cli",
|
|
3
|
+
"version": "0.1.1-alpha.0",
|
|
4
|
+
"description": "Read-only agent-facing CLI over the Sentora vault packages: vault state, unsigned tx plans, yields API",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": {
|
|
7
|
+
"smart-yield": "./dist/cli.mjs"
|
|
8
|
+
},
|
|
9
|
+
"files": [
|
|
10
|
+
"dist",
|
|
11
|
+
"!dist/**/*.map",
|
|
12
|
+
"skills",
|
|
13
|
+
"README.md"
|
|
14
|
+
],
|
|
15
|
+
"devDependencies": {
|
|
16
|
+
"@sentora/vaults-boring": "*",
|
|
17
|
+
"@sentora/vaults-morpho": "*",
|
|
18
|
+
"@sentora/vaults-plan": "*",
|
|
19
|
+
"@sentora/vaults-upshift-financial": "*",
|
|
20
|
+
"@sentora/yields-client": "*",
|
|
21
|
+
"@types/node": "^22",
|
|
22
|
+
"esbuild": "^0.25.0",
|
|
23
|
+
"typescript": "^5.6.0",
|
|
24
|
+
"viem": "2.55.15"
|
|
25
|
+
}
|
|
26
|
+
}
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: smart-yield
|
|
3
|
+
description: >-
|
|
4
|
+
Discover Sentora/DeFi vaults, evaluate yield (APY, TVL, risk), read wallet
|
|
5
|
+
positions, and build UNSIGNED deposit/withdraw/redeem transaction plans as
|
|
6
|
+
JSON via the smart-yield CLI. Use when the user asks about vaults, yields,
|
|
7
|
+
APY, deposits, withdrawals, redemptions, or portfolio positions on Sentora
|
|
8
|
+
SmartYield. Not for signing, sending, or broadcasting transactions — plans
|
|
9
|
+
are handed to an external signer.
|
|
10
|
+
allowed-tools: Bash(smart-yield *), Bash(npx smart-yield *)
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# smart-yield — read-only vault CLI
|
|
14
|
+
|
|
15
|
+
Every command is a query: it reads vault state or builds an UNSIGNED
|
|
16
|
+
transaction plan. Nothing here signs or sends.
|
|
17
|
+
|
|
18
|
+
## Learn the surface
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
smart-yield describe # full command surface as JSON: families, flags, examples, exit codes
|
|
22
|
+
smart-yield describe --family boring # one family only
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Grammar: `smart-yield <family> <command> [flags]`. Families: `morpho`,
|
|
26
|
+
`boring`, `upshift-financial` (on-chain via RPC) and `yields` (Sentora API).
|
|
27
|
+
Top-level: `describe`, `detect --vault 0x…`, `snapshot --vault 0xA[,0xB…]`.
|
|
28
|
+
|
|
29
|
+
## Typical workflow
|
|
30
|
+
|
|
31
|
+
```sh
|
|
32
|
+
# 1. discover vaults (filter + project fields to stay token-lean)
|
|
33
|
+
smart-yield yields list --chain 1 --fields name,family,contracts
|
|
34
|
+
|
|
35
|
+
# 2. evaluate performance (summary stats, never raw series)
|
|
36
|
+
smart-yield yields analytics --chain-id 1 --address 0xVAULT --days 30 --summary
|
|
37
|
+
|
|
38
|
+
# 3. preflight candidates in ONE call: family + meta (+ gates/position with --owner)
|
|
39
|
+
smart-yield snapshot --vault 0xA,0xB --owner 0xYOU --rpc-url $RPC
|
|
40
|
+
|
|
41
|
+
# 4. build the unsigned plan
|
|
42
|
+
smart-yield upshift-financial plan-deposit --vault 0xA --amount 100.5 --human --owner 0xYOU --rpc-url $RPC
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Plan safety — non-negotiable
|
|
46
|
+
|
|
47
|
+
- A plan's `steps` are unsigned `{to, data, value}` transactions for an
|
|
48
|
+
external signer, executed strictly in order, waiting for each receipt.
|
|
49
|
+
- Non-empty `blockers` ⇒ exit code 7 ⇒ the plan MUST NOT be executed, even
|
|
50
|
+
though it is printed.
|
|
51
|
+
- Never fabricate or edit step calldata; regenerate the plan instead.
|
|
52
|
+
|
|
53
|
+
## Output and exit codes
|
|
54
|
+
|
|
55
|
+
- stdout is data: compact JSON, bigints as decimal strings (`--pretty`,
|
|
56
|
+
`--output text` for `path=value` lines). stderr carries errors as
|
|
57
|
+
`{"error":{"code","message","retryable","hint"}}` — follow the `hint`, and
|
|
58
|
+
retry only when `retryable` is true.
|
|
59
|
+
- Exit codes: 0 ok · 1 unexpected · 2 usage · 3 not found · 4 rpc/network
|
|
60
|
+
(retryable) · 5 upstream api · 6 contract revert · 7 plan blocked.
|
|
61
|
+
- Amounts are base units by default; `--human` accepts decimals (`100.5`) and
|
|
62
|
+
scales by on-chain token decimals. Outputs include human-decimal twins
|
|
63
|
+
(`formatted` / `expectedFormatted`) where decimals are known.
|
|
64
|
+
- Pagination: `--limit/--offset/--fields` on list commands; responses report
|
|
65
|
+
`total/truncated/remaining` — truncation is never silent.
|
|
66
|
+
|
|
67
|
+
## Configuration (env-only secrets)
|
|
68
|
+
|
|
69
|
+
- RPC endpoint: `--rpc-url` flag, else `VAULTS_RPC_URL` / `SENTORA_RPC_URL` /
|
|
70
|
+
`ETH_RPC_URL`.
|
|
71
|
+
- Yields API: `YIELDS_BASE_URL` (or `SENTORA_API_URL`; defaults to production)
|
|
72
|
+
and `YIELDS_API_KEY` (or `SENTORA_API_KEY`). The API key cannot be passed as
|
|
73
|
+
a flag and is only sent to the default or env-configured origin.
|
|
74
|
+
- `--timeout <ms>` bounds every network call (default 30000).
|
|
75
|
+
|
|
76
|
+
## Gotchas
|
|
77
|
+
|
|
78
|
+
- Pipes mask exit codes (`$?` is the last pipeline element) — branch on
|
|
79
|
+
`${PIPESTATUS[0]}` or run unpiped. `npm run` also flattens exit codes;
|
|
80
|
+
invoke the bin directly.
|
|
81
|
+
- Network failures inside an agent sandbox (e.g. Codex with egress disabled)
|
|
82
|
+
return exit 4 with a hint naming the sandbox fix — read the hint before
|
|
83
|
+
retrying.
|