@tokagent/tokagentos 2.0.13 → 2.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokagent/tokagentos",
-  "version": "2.0.13",
+  "version": "2.0.15",
   "description": "tokagentOS CLI - Create and upgrade tokagentOS project templates",
   "type": "module",
   "bin": {

package/templates/fullstack-app/plugins/plugin-tokagent-billing/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokagent/plugin-tokagent-billing",
-  "version": "2.0.6",
+  "version": "2.0.8",
   "description": "elizaOS plugin: Web3 credit-billing routes and middleware for the tokagentos LLM gateway.",
   "type": "module",
   "publishConfig": { "access": "public" },

package/templates/fullstack-app/plugins/plugin-tokagent-billing/src/dashboard/app.js

@@ -716,10 +716,15 @@ function renderTopBar() {
 
 function renderKpis() {
   const c = state.credits;
-  const balance = c?.ledger?.balance ?? c?.onChainCredits;
+  // Server returns BOTH nested (c.ledger.balance) and flat (c.balance).
+  // Prefer nested for clients that expect the structured shape, fall back
+  // to flat for forward/backward compat with the simpler API surface.
+  const balance = c?.ledger?.balance ?? c?.balance ?? c?.onChainCredits;
+  const reserved = c?.ledger?.reserved ?? c?.reserved ?? 0n;
+  const accrued = c?.ledger?.accrued ?? c?.accrued ?? 0n;
   $("#kpi-balance").textContent = fmtPton(balance);
-  $("#kpi-reserved").textContent = fmtPton(c?.ledger?.reserved ?? 0n) + " PTON";
-  $("#kpi-accrued").textContent = fmtPton(c?.ledger?.accrued ?? 0n) + " PTON";
+  $("#kpi-reserved").textContent = fmtPton(reserved) + " PTON";
+  $("#kpi-accrued").textContent = fmtPton(accrued) + " PTON";
   $("#kpi-balance-usd").textContent = fmtUsdFromAttoPton(balance, state.tonUsd);
   // Wallet holdings (outside the vault). ETH and PTON share 18 decimals so
   // fmtPton works for both — only the unit label differs.

package/templates/fullstack-app/plugins/plugin-tokagent-billing/src/routes/credits-routes.ts

@@ -19,7 +19,7 @@ import {
 } from "../state.js";
 import { resolveBillingIdentity } from "../middleware/api-key-resolve.js";
 import { pickForward, forward, ensureClientReady } from "../lib/forward.js";
-import { creditState } from "@tokagentos/billing";
+import { creditState, hydrate as hydrateCredits, readCredits } from "@tokagentos/billing";
 import { eq } from "drizzle-orm";
 
 // ---------------------------------------------------------------------------
@@ -63,7 +63,7 @@ async function handleGetCreditsMe(
   _runtime: IAgentRuntime,
 ): Promise<void> {
   if (!isBillingStateInitialized()) return billingUnavailable(res);
-  const { db, config } = getServerBillingState();
+  const { db, config, clients } = getServerBillingState();
   if (!config.enabled) return billingUnavailable(res);
 
   const identity = await resolveBillingIdentity(toIncomingMessage(req));
@@ -75,6 +75,35 @@ async function handleGetCreditsMe(
   const wallet: Address = identity.wallet;
   const walletKey = wallet.toLowerCase();
 
+  // Sync on-chain credits → DB ledger BEFORE returning the balance.
+  //
+  // Why hydrate-on-read instead of a separate deposit watcher service:
+  //   - depositX402 is now PERMISSIONLESS (any wallet can submit a user's
+  //     signed EIP-3009 auth) — handleTopupSettle is only ONE possible
+  //     submitter, so we can't rely on the settle path to credit the DB.
+  //   - A dedicated event listener could miss events during agent
+  //     downtime or RPC outages; hydrate-on-read self-heals at request
+  //     time.
+  //   - The vault's `credits[user]` mapping is the source of truth.
+  //     hydrate() reconciles: balance = onChain - (reserved + accrued).
+  //
+  // Costs: one eth_call per dashboard refresh. Acceptable — this route is
+  // not on the hot inference path.
+  //
+  // Failure handling: if the RPC call throws, fall back to the stale DB
+  // row rather than 500ing. The user sees a slightly old balance instead
+  // of a broken page.
+  try {
+    const onChainCredits = await readCredits(
+      clients,
+      config.vaultAddress,
+      wallet,
+    );
+    await hydrateCredits(db, wallet, onChainCredits);
+  } catch (_err) {
+    // Swallow — fall back to whatever the DB has. Logged at hydrate level.
+  }
+
   // Read the credit state row (may not exist for a new wallet).
   const rows = await db
     .select()
@@ -83,11 +112,19 @@ async function handleGetCreditsMe(
 
   const row = rows[0];
 
+  // Response shape: both flat (legacy clients) and nested under `ledger`
+  // (the dashboard SPA which reads `c.ledger.balance`). Keeping both keys
+  // is cheap and avoids a contract break for any external caller already
+  // depending on the flat shape.
+  const balance = row ? row.balance.toString() : "0";
+  const reserved = row ? row.reserved.toString() : "0";
+  const accrued = row ? row.accrued.toString() : "0";
   res.status(200).json({
     wallet,
-    balance: row ? row.balance.toString() : "0",
-    reserved: row ? row.reserved.toString() : "0",
-    accrued: row ? row.accrued.toString() : "0",
+    balance,
+    reserved,
+    accrued,
+    ledger: { balance, reserved, accrued },
   });
 }
 

package/templates/fullstack-app/plugins/plugin-tokagent-billing/src/routes/estimate-routes.ts

@@ -263,7 +263,7 @@ async function handleCountTokens(
  * or `{ "available": false }` when no price is cached.
  */
 async function handlePrice(
-  req: RouteRequest,
+  _req: RouteRequest,
   res: RouteResponse,
   _runtime: IAgentRuntime,
 ): Promise<void> {
@@ -271,11 +271,9 @@ async function handlePrice(
   const { config, twapCache } = getBillingState();
   if (!config.enabled) return billingUnavailable(res);
 
-  const identity = await resolveBillingIdentity(toIncomingMessage(req));
-  if (!identity) {
-    res.status(401).json({ error: "Authentication required." });
-    return;
-  }
+  // TON/USD is a public oracle read — no identity required. The dashboard
+  // KPI shows this rate before the user has signed in, so gating it on
+  // SIWE auth would leave the price displayed as "—" until login completes.
 
   // 1. Priority override — operator-pinned price freeze.
   //    `BILLING_FIXED_TON_USD` is env-only (not exposed in the setup wizard),

package/templates/fullstack-app/plugins/plugin-tokagent-billing/src/routes/topup-routes.ts

@@ -194,26 +194,53 @@ async function handleTopupQuote(
     return;
   }
 
-  // Parse optional amountUsd from body; fall back to the configured default.
+  // Parse optional amountPton OR amountUsd from body; fall back to default.
+  // Prefer amountPton when both are present — it's the exact value the user
+  // signs in the EIP-3009 authorization, and settlement strictly equality-
+  // checks signature.value === quote.amountPton. Routing the user's intent
+  // through a USD round-trip would round and mismatch the signature.
   const body = req.body as Record<string, unknown> | undefined;
+  let amountPton: bigint;
   let amountUsd: number;
-  if (body?.["amountUsd"] !== undefined) {
+  if (body?.["amountPton"] !== undefined) {
+    const raw = body["amountPton"];
+    let parsed: bigint;
+    try {
+      // Accept either a decimal string (atto-units) or a JS number for
+      // backward compat with older clients.
+      if (typeof raw === "string") parsed = BigInt(raw);
+      else if (typeof raw === "number" && Number.isFinite(raw) && raw > 0)
+        parsed = BigInt(Math.floor(raw));
+      else throw new Error("amountPton must be a positive decimal string or number (atto-units)");
+    } catch (e) {
+      res.status(400).json({
+        error: e instanceof Error ? e.message : "Invalid amountPton",
+      });
+      return;
+    }
+    if (parsed <= 0n) {
+      res.status(400).json({ error: "amountPton must be > 0" });
+      return;
+    }
+    amountPton = parsed;
+    // Derive USD for the response envelope. Settlement only checks PTON.
+    amountUsd = (Number(amountPton) / 1e18) * tonUsd;
+  } else if (body?.["amountUsd"] !== undefined) {
     const raw = body["amountUsd"];
     if (typeof raw !== "number" || !Number.isFinite(raw) || raw <= 0) {
       res.status(400).json({ error: "amountUsd must be a positive finite number." });
       return;
     }
     amountUsd = raw;
+    amountPton = usdToPton(amountUsd, tonUsd);
   } else {
-    // Convert default PTON amount → USD.
-    const defaultPton = config.topupAmountPton;
-    // amountUsd = ptonAmount * tonUsd / 1e18
-    amountUsd = Number(defaultPton) * tonUsd / 1e18;
+    // Neither provided — use configured default PTON amount.
+    amountPton = config.topupAmountPton;
+    amountUsd = Number(amountPton) * tonUsd / 1e18;
   }
 
-  const amountPton = usdToPton(amountUsd, tonUsd);
   if (amountPton <= 0n) {
-    res.status(400).json({ error: "Computed PTON amount is zero — check amountUsd." });
+    res.status(400).json({ error: "Computed PTON amount is zero — check amount." });
     return;
   }
 

package/templates-manifest.json

@@ -1,6 +1,6 @@
 {
   "version": "1.0.0",
-  "generatedAt": "2026-05-19T14:16:04.436Z",
+  "generatedAt": "2026-05-19T17:46:05.725Z",
   "repoUrl": "https://github.com/elizaos/eliza",
   "templates": [
     {