feat: R1 SDK truthfulness + CLI earn-compare + token-receive (v0.2.1)#13
Merged
Conversation
…VERY_ONLY guard (v0.2.0)
Bumps @toreva/sdk 0.1.1 → 0.2.0 and ships honest R1 surface area:
- New earnCompare({ asset:'USDC', venue:'kamino'|'marginfi' }) — calls live
mcp.toreva.com /mcp JSON-RPC tools/call. Returns canonical APY snapshot
with the evidence triple (readEvidenceId, venueIntelligenceReceiptId,
sentinelReviewReceiptId) for downstream audit.
- New tokenReceive({ wallet, limit }) — calls toreva_token_receive_scan.
Returns recent inbound SPL token transfers, evidence-attached.
- perps.ts: every exported function (PerpsApi.call, openLong, openShort,
closePosition, addMargin, removeMargin, cancelOrder) now throws
DISCOVERY_ONLY with a roadmap link instead of silently returning
CLASS_A_PENDING. Type exports retained for IDE discoverability.
- @toreva/mcp tools/perps.ts: perpsToolDefinitions[].discovery_only=true
flag so the surface advertises honestly that the perps tool/call path
is gated until R3.
- README.md: per-family operational matrix sourced from gateway DoD
matrix v1. Every row tagged DISCOVERY_ONLY / NOT YET OPERATIONAL where
applicable. Tier definitions T0–T5. R1 is exactly 3 primitives.
- package.json description rewritten to truthful R1 framing; keywords
trimmed to remove perps overclaims and add kamino/marginfi/spl-token.
- tsconfig: exclude __tests__ from publish dist.
Tests: vitest packages/sdk/src/__tests__/r1.test.ts — 16 cases covering
shape, runtime venue/asset rejection, JSON-RPC envelope, error paths,
DISCOVERY_ONLY guard for every perps export. All green (94/94 across kit).
Closes the SDK over-claim risk flagged in plan addendum 2 Phase A. Flips
two DoD matrix gates ✅ for earn_lending and token_ops:
- sdk_kit_wired_and_tested (file present + tests pass)
The CLI gate is unblocked by the companion CLI commit.
Published: @toreva/sdk@0.2.0 → npm registry (latest tag).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… to live MCP
Phase B of plan addendum 2. Adds two new CLI commands wiring the R1
read-only primitives end-to-end against the live mcp.toreva.com server.
CLI changes (packages/cli):
- New `toreva earn-compare --asset USDC --venue <kamino|marginfi>` command
in src/commands/earn-compare.ts. Calls SDK earnCompare(), formats result
as a human table including the evidence triple.
- New `toreva token-receive --wallet <addr> [--limit <n>]` command in
src/commands/token-receive.ts. Calls SDK tokenReceive(), formats receive
events with sender/mint/amount/signature columns and the evidence triple.
- Wired both commands into src/index.ts dispatch + USAGE help.
- Tests in src/__tests__/earn-compare.test.ts + token-receive.test.ts —
arg parser cases, formatter renderings, command runner with SDK mocked.
Mirrors the existing scan/doctor pattern; uses vi.mock('@toreva/sdk').
- Bumped @toreva/cli 0.1.1 → 0.2.0; description rewritten to truthful R1
framing; keywords trimmed.
SDK shape alignment to live MCP (packages/sdk):
- earnCompare: apyPct now `number | null` to match marginfi's "live but
not-yet-decoded" payload (the live tool returns `apyPct: null` plus an
`apyNote` string explaining the IDL deserialization is owned by
network-sol). Added marginfi-specific fields (bankAccount, bankOwner,
bankLamports, bankDataSha256, slot) to the result type.
- tokenReceive: live MCP tool uses `walletAddress` (not `wallet`) as the
argument name and returns `events[]` (not `receives[]`) with
`inspectedSignatureCount` + `totalSignatureCountReturned` counts. SDK
now sends the canonical `walletAddress` to MCP while keeping the
ergonomic `wallet` parameter for callers, and surfaces both canonical
fields and ergonomic aliases (wallet, count, receives) on the result.
- tokenReceive: limit cap lowered 1000 → 25 to match the live MCP tool's
documented max.
- tokenReceive: error path now propagates the live MCP `isError` payload's
upstream message (e.g. "walletAddress (...) is required") instead of a
generic "error payload" string.
- Bumped @toreva/sdk 0.2.0 → 0.2.1 to ship the shape fix.
Verified end-to-end against mcp.toreva.com:
$ TOREVA_API_KEY=tk_litmus_r1_synthetic_3rd_party_trading_bot_demo_only \
node packages/cli/dist/index.js earn-compare --asset USDC --venue kamino
Venue kamino
APY 4.0317% (real DefiLlama snapshot)
Source defillama
evidence triple: NETSOL-READ-... / VS-... / SENT-REVIEW-...
Tests: 115/115 green (pnpm test). 20 new CLI cases. Builds clean.
Published @toreva/sdk@0.2.1 → npm registry (latest tag).
@toreva/cli is intentionally NOT published until full CLI publishing
workflow lands (CLI ships per-monorepo via pnpx/npx today).
Flips DoD matrix gates ✅:
- sdk_kit_wired_and_tested for earn_lending + token_ops
- cli_wired_and_tested for earn_lending + token_ops
Combined with the existing T1 admission state, both families should
advance T1 → T2 (read-only operational) on the next `pnpm regenerate-dod`.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c6ddba60f8
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| fetchImpl?: typeof fetch; | ||
| } | ||
|
|
||
| const DEFAULT_MCP_URL = 'https://mcp.toreva.com'; |
There was a problem hiding this comment.
The /workspace/kit instructions and repo charter require thin clients to call only gateway.toreva.com via the relay protocol, but this new SDK path defaults to https://mcp.toreva.com and then POSTs JSON-RPC tools/call directly to /mcp (the same pattern is duplicated in tokenReceive). Any consumer using the new SDK/CLI commands will bypass the gateway/relay boundary, so this should be wired through the existing gateway relay client instead of a direct MCP endpoint.
Useful? React with 👍 / 👎.
Comment on lines
+5
to
+6
| > **Truthfulness rule.** This README is generated against the gateway's | ||
| > [operational definition-of-done matrix](https://github.com/toreva/gateway/blob/main/docs/operational-definition-of-done-matrix.v1.md). |
There was a problem hiding this comment.
The repo guardrails explicitly forbid committing internal docs/source-of-truth pointers and unreleased operational details to this public thin-client repo. Because the SDK README is published with the package, linking the gateway operational DoD matrix here (and the subsequent roadmap/admission-gate details in this README) exposes exactly the kind of internal source pointer/topology the guardrail says to route elsewhere; keep this doc limited to public supported behavior.
Useful? React with 👍 / 👎.
PR #13's SDK perps DISCOVERY_ONLY guards imported these type names but they were never exported from @toreva/types. Build fails with TS2305 in packages/sdk/src/perps.ts. Adding generic-but-permissive shapes since the DISCOVERY_ONLY guards throw before either type is exercised. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
SDK perps.ts uses PerpsToolResult<TToolName> (generic). Previous fix defined it non-generic causing TS2315. Adding tool-name type parameter (currently unused but reserved for per-tool result discrimination in R3 when execution lands). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase A + B of plan addendum 2 — drives R1 to truthful end-to-end coverage for the only two T1 families (
earn_lending,token_ops) on the operational definition-of-done matrix:@toreva/sdk@0.2.1published to npm): newearnCompare()+tokenReceive()calling livemcp.toreva.com.perps.*now throwsDISCOVERY_ONLYinstead of silently returningCLASS_A_PENDING. Description rewritten honestly. README ships per-family operational matrix.@toreva/mcp): perps tool definitions flaggeddiscovery_only: true.@toreva/cli@0.2.0): newtoreva earn-compare --asset USDC --venue <kamino|marginfi>andtoreva token-receive --wallet <addr> [--limit <n>]commands wired into the dispatch + USAGE.Verification
pnpm test). 36 new cases (16 SDK, 20 CLI).mcp.toreva.com:kamino earn-compare USDC→ real DefiLlama APY (4.0317% at run time).marginfi earn-compare USDC→ live mainnet bank state (apyPct null + apyNote, by design — see network-sol owns IDL deserialization).token-receive→ live Solana RPC scan, returns events array + evidence triple.@toreva/sdk@0.2.1to npm registry,latesttag.DoD matrix gates flipped
gateway pnpm regenerate-dodafter merge will flip:sdk_kit_wired_and_tested✅ forearn_lending(file:src/earn.ts) andtoken_ops(file:src/tokens.ts).cli_wired_and_tested✅ forearn_lending(file:commands/earn-compare.ts) andtoken_ops(file:commands/token-receive.ts).Combined with existing T1 admission state, both families should advance T1 → T2 (read-only operational) on the next regen — taking the headline tier rollup from
T1=2 / T2=0toT1=0 / T2=2.Truthfulness
earnCompare()calls realmcp.toreva.com, returns real APY (kamino) or live bank state (marginfi). Tests mock fetch but real CLI invocations hit prod.perps.openLong()(and friends) throwsDISCOVERY_ONLYwith link to https://toreva.com/roadmap. No more silent CLASS_A_PENDING returns.DISCOVERY_ONLY/NOT YET OPERATIONALstatus.apyPct: null+apyNoteto honour the "real APY decoding lives in network-sol" disclosure.Test plan
npm view @toreva/sdk@0.2.1shows the new descriptionpnpm regenerate-dodin gateway → confirm T2 count increments to 2pnpm tier-rollupin gateway → headline metric🤖 Generated with Claude Code