@mysten-incubation/sui-agent-pass 0.1.3 → 0.1.5

package/README.md

@@ -334,11 +334,8 @@ brand` and `npx playwright install chromium`.
 - [Agent transaction guide](docs/AGENT.md): complete interface and agent-side examples.
 - [Architecture and boundaries](docs/ARCHITECTURE.md).
 - [Status: implemented and todo](docs/STATUS.md).
-- [Verification record](docs/VERIFICATION.md) and [generated chain evidence](docs/evidence/localnet.json),
-  including the explorer's [pass page](docs/evidence/explorer-pass.png) and
-  [booth view](docs/evidence/explorer-booth.png).
-- [Real Claude execution evidence](docs/evidence/claude.json): Claude Code with the plugin,
-  from prompt to signed pass to on-chain actions on a localnet.
+- [Verification record](docs/VERIFICATION.md): dated runs with their digests. The test scripts
+  write their reports and screenshots to `.local/evidence/`, which stays out of git.
 
 ## Checks
 

package/dist/describe.js

@@ -7,7 +7,7 @@
  */
 import { bcs } from '@mysten/sui/bcs';
 import { fromBase64, normalizeSuiAddress } from '@mysten/sui/utils';
-import { priceDisplay, sameCoin, showCoin, SUI, } from './domain.js';
+import { limitDisplay, priceTerms, sameCoin, showCoin, SUI, } from './domain.js';
 const healthFactor = (ray) => (Number(BigInt(ray) / 10n ** 25n) / 100).toFixed(2);
 /** The reviewed rules, or the installed policies once `live` is read from chain. */
 export function describePolicy(d, p, live = null) {
@@ -34,32 +34,37 @@ export function describePolicy(d, p, live = null) {
     for (const t of p.transfers) {
         const l = live?.transfers.find((x) => sameCoin(x.coinType, t.coin));
         rows.push({
+            starts: true,
             label: `Pay ${symbol(t.coin)} to`,
             value: (l?.recipients ?? t.recipients).map((r) => `${r.name} → ${r.address}`).join('\n'),
         }, {
-            label: `${symbol(t.coin)} per transfer · per UTC day`,
-            value: `${show(t.coin, l?.perTransfer ?? t.perTransfer)} · ${show(t.coin, l?.daily ?? t.daily)}`,
+            label: `Max ${symbol(t.coin)} per transfer / per UTC day`,
+            value: `${show(t.coin, l?.perTransfer ?? t.perTransfer)} / ${show(t.coin, l?.daily ?? t.daily)}`,
         });
     }
     for (const sw of p.swaps) {
         const l = live?.swaps.find((x) => sameCoin(x.coinIn, sw.coinIn) && sameCoin(x.coinOut, sw.coinOut));
-        const minPrice = l?.minPrice ?? sw.minPrice;
+        const minPrice = l?.minPrice ?? sw.minPrice, terms = priceTerms(d, sw.coinIn, sw.coinOut);
         rows.push({
-            label: `Sell ${symbol(sw.coinIn)} for ${symbol(sw.coinOut)} on`,
+            starts: true,
+            label: terms.limit === 'max'
+                ? `Buy ${symbol(sw.coinOut)} with ${symbol(sw.coinIn)} on`
+                : `Sell ${symbol(sw.coinIn)} for ${symbol(sw.coinOut)} on`,
             value: (l?.venues ?? sw.pools).map(poolName).join(', '),
         }, {
-            label: `${symbol(sw.coinIn)} per trade · per UTC day`,
-            value: `${show(sw.coinIn, l?.perTrade ?? sw.perTrade)} · ${show(sw.coinIn, l?.daily ?? sw.daily)}`,
+            label: `Max ${symbol(sw.coinIn)} ${terms.limit === 'max' ? 'spent' : 'sold'} per trade / per UTC day`,
+            value: `${show(sw.coinIn, l?.perTrade ?? sw.perTrade)} / ${show(sw.coinIn, l?.daily ?? sw.daily)}`,
         }, {
-            label: 'Lowest price accepted',
-            value: `${priceDisplay(d, sw.coinIn, sw.coinOut, minPrice)} ${symbol(sw.coinOut)} per ${symbol(sw.coinIn)}`,
+            label: terms.limit === 'max' ? 'Highest price paid' : 'Lowest price accepted',
+            value: `${limitDisplay(d, sw.coinIn, sw.coinOut, minPrice)} ${symbol(terms.quote)} per ${symbol(terms.base)}`,
         });
     }
     for (const le of p.lending) {
         const l = live?.lending.find((x) => sameCoin(x.coinType, le.coin));
         rows.push({
-            label: `NAVI ${le.allowBorrow ? 'borrowing' : 'collateral'} in ${symbol(le.coin)}, per action · per UTC day`,
-            value: `${show(le.coin, l?.perAction ?? le.perAction)} · ${show(le.coin, l?.daily ?? le.daily)}`,
+            starts: true,
+            label: `Max NAVI ${le.allowBorrow ? 'borrowing' : 'collateral'} in ${symbol(le.coin)} per action / per UTC day`,
+            value: `${show(le.coin, l?.perAction ?? le.perAction)} / ${show(le.coin, l?.daily ?? le.daily)}`,
         });
         const floor = l ? healthFactor(l.minHealthFactor) : le.minHealthFactor?.toFixed(2);
         if (floor && floor !== '0.00')
@@ -69,11 +74,12 @@ export function describePolicy(d, p, live = null) {
         const l = live?.staking[0];
         const validators = l?.validators ?? p.staking.validators;
         rows.push({
+            starts: true,
             label: 'Stake SUI with',
             value: validators.length ? validators.join('\n') : 'Any active validator',
         }, {
-            label: 'SUI per stake · per UTC day',
-            value: `${show(SUI, l?.perStake ?? p.staking.perStake)} · ${show(SUI, l?.daily ?? p.staking.daily)}`,
+            label: 'Max SUI per stake / per UTC day',
+            value: `${show(SUI, l?.perStake ?? p.staking.perStake)} / ${show(SUI, l?.daily ?? p.staking.daily)}`,
         });
     }
     return rows;
@@ -88,6 +94,7 @@ export function describeSetup(d, setup) {
     return [
         ...describePolicy(d, setup.policy),
         {
+            starts: true,
             label: 'Authorization ends',
             value: `${utc.format(setup.expiresMs)} UTC (${setup.ttlMs / 86_400_000} ${setup.ttlMs === 86_400_000 ? 'day' : 'days'}); you can revoke earlier`,
         },
@@ -95,11 +102,11 @@ export function describeSetup(d, setup) {
             label: 'Agent may ever withdraw (lifetime caps)',
             value: Object.entries(setup.allowances)
                 .map(([coin, cap]) => showCoin(d, coin, cap))
-                .join(' · '),
+                .join(', '),
         },
         {
-            label: 'Gas allowance, lifetime · per UTC day',
-            value: `${showCoin(d, SUI, setup.gasCap)} · ${showCoin(d, SUI, setup.gasDaily)}`,
+            label: 'Max gas allowance, lifetime / per UTC day',
+            value: `${showCoin(d, SUI, setup.gasCap)} / ${showCoin(d, SUI, setup.gasDaily)}`,
         },
         {
             label: 'Agent gas stipend (outside the rules)',
@@ -107,7 +114,9 @@ export function describeSetup(d, setup) {
         },
     ];
 }
-export const renderRows = (rows) => rows.map(({ label, value }) => `- ${label}: ${value.replaceAll('\n', '; ')}`).join('\n');
+export const renderRows = (rows) => rows
+    .map(({ label, value, starts }, i) => `${starts && i > 0 ? '\n' : ''}- ${label}: ${value.replaceAll('\n', '; ')}`)
+    .join('\n');
 const OWNER_ONLY = new Set([
     'deposit_object',
     'withdraw_object',
@@ -317,7 +326,7 @@ export function describeRefusal(d, error, recipient) {
             0: 'Not a pool you listed',
             1: 'Over your per-trade limit',
             3: "Below the agent's own minimum output",
-            4: 'Below your price floor',
+            4: 'Worse than your price limit',
             8: 'The venue filled nothing (order under its minimum size)',
         },
         lending_policy: {

package/dist/domain.js

@@ -349,6 +349,36 @@ export function priceDisplay(d, coinIn, coinOut, minPrice) {
         ? display(minPrice, shift)
         : (BigInt(minPrice) * 10n ** BigInt(-shift)).toString();
 }
+/** Dollar stablecoins by symbol: USDC, USDT, USDY, USDsui and the like. */
+export const isStable = (symbol) => /^(USD|AUSD$|FDUSD$|BUCK$)/i.test(symbol);
+/**
+ * How a swap rule's price reads to a person. When exactly one side is a stablecoin the price is
+ * in that stablecoin per one of the other coin, so a buy reads as the most paid (the policy's
+ * floor inverted) and a sale as the least accepted. Otherwise it is `coinOut` per one `coinIn`.
+ */
+export function priceTerms(d, coinIn, coinOut) {
+    const stableIn = isStable(coinInfo(d, coinIn).symbol), stableOut = isStable(coinInfo(d, coinOut).symbol);
+    return stableIn && !stableOut
+        ? { base: coinOut, quote: coinIn, limit: 'max' }
+        : { base: coinIn, quote: coinOut, limit: 'min' };
+}
+/** The policy floor for a person's price in `priceTerms`; a buy's maximum rounds the floor up. */
+export function limitUnits(d, coinIn, coinOut, price) {
+    if (priceTerms(d, coinIn, coinOut).limit === 'min')
+        return priceUnits(d, coinIn, coinOut, price);
+    const paid = BigInt(units(price, coinInfo(d, coinIn).decimals));
+    if (paid === 0n)
+        throw new Error('A price must be above 0');
+    const scale = 10n ** BigInt(coinInfo(d, coinOut).decimals) * 10n ** 9n;
+    return ((scale + paid - 1n) / paid).toString();
+}
+/** A policy floor as a person reads it, in `priceTerms`, without the coin names. */
+export function limitDisplay(d, coinIn, coinOut, minPrice) {
+    if (priceTerms(d, coinIn, coinOut).limit === 'min')
+        return priceDisplay(d, coinIn, coinOut, minPrice);
+    const floor = BigInt(minPrice), scale = 10n ** BigInt(coinInfo(d, coinOut).decimals) * 10n ** 9n;
+    return display(((scale * 2n + floor) / (floor * 2n)).toString(), coinInfo(d, coinIn).decimals);
+}
 /** Health factors are entered with two decimals and stored on chain in ray units. */
 export const healthFactorRay = (hf) => hf === null ? '0' : ((BigInt(units(hf.toFixed(2), 2)) * RAY) / 100n).toString();
 /** Gas top-ups per UTC day when the owner names none: a fifth of the lifetime cap, so a runaway

package/dist/plugin.js

@@ -20,9 +20,9 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
 import { Transaction } from '@mysten/sui/transactions';
 import { fromBase64, normalizeSuiAddress } from '@mysten/sui/utils';
 import { z } from 'zod';
-import { clientFor, deepbookSizes, quoteSwap, readStatus, withMarketFacts } from './chain.js';
+import { clientFor, deepbookSizes, quoteSwap, readAllHoldings, readStatus, withMarketFacts, } from './chain.js';
 import { describePolicy, describeSetup, renderRows } from './describe.js';
-import { address, coinBySymbol, coinInfo, DAY_MS, defaultGasDaily, DeploymentSchema, display, poolsFor, priceUnits, recipientName, sameCoin, SetupSchema, showCoin, units, VenueSchema, } from './domain.js';
+import { address, coinBySymbol, coinInfo, DAY_MS, defaultGasDaily, DeploymentSchema, display, isStable, limitUnits, poolsFor, recipientName, sameCoin, SetupSchema, showCoin, units, VenueSchema, } from './domain.js';
 import { passesByAgent } from './explorer.js';
 import { passEnded, returnGasFloat } from './float.js';
 import { failure, INSTRUCTIONS, registerDocs, result, sessionInfo, SIGN_ANNOTATIONS, SIGN_DESCRIPTION, } from './mcp.js';
@@ -236,7 +236,7 @@ const rulesInput = {
             .describe('pool object ids for a pair the deployment does not list (a DeepBook or Cetus pool holding exactly these two coins); verified on chain'),
         perTrade: decimal.describe('sold coin per trade'),
         daily: decimal.describe('sold coin per UTC day'),
-        minPrice: decimal.describe("lowest price accepted, in bought coin per one sold coin; required, above 0. When the owner names no floor, 1% under the pool's current price (list_passes shows it) and say so"),
+        limitPrice: decimal.describe("the owner's price limit. With a stablecoin on one side it is that stablecoin per one of the other coin: the most paid when buying, the least accepted when selling. Otherwise it is bought coin per one sold coin, the least accepted. Required, above 0, and only the owner sets it: ask them, showing the pool's current price from list_passes"),
     })
         .strict())
         .default([])
@@ -319,7 +319,7 @@ async function toSetup(client, d0, input) {
                     pools: pools.map((p) => p.poolId),
                     perTrade: inUnits(sw.sell, sw.perTrade),
                     daily: inUnits(sw.sell, sw.daily),
-                    minPrice: priceUnits(d, coinIn, coinOut, sw.minPrice),
+                    minPrice: limitUnits(d, coinIn, coinOut, sw.limitPrice),
                 };
             }),
             lending: input.lending.map((l) => {
@@ -411,17 +411,22 @@ export function createPluginMcp(registry) {
     });
     registerDocs(server);
     server.registerTool('list_passes', {
-        description: 'List the pass sessions on this machine (id, name, network, whether the owner has authorized it on chain) and the networks a new pass can live on, each with the coins and pools its rules may name.',
-        inputSchema: {},
+        description: 'List the pass sessions on this machine (id, name, network, whether the owner has authorized it on chain) and the networks a new pass can live on, each with its listed coins and pools and how to name others. With owner, also every coin that address holds on each network, so rules can be sized from real balances before any pass exists.',
+        inputSchema: {
+            owner: address
+                .optional()
+                .describe("the owner's address, when they gave it; adds ownerCoins per network"),
+        },
         annotations: { readOnlyHint: true },
-    }, async () => {
+    }, async ({ owner }) => {
         const path = registry.deploymentPath();
-        // The pool's own price for ten units of coinA, so a floor can be sized from the market
-        // before any pass exists; ten clears DeepBook's minimum order where one may not.
+        // What the pool pays for ten units of its non-stable coin (coinA when neither or both are
+        // stablecoins), quoted like a rule's price; ten clears DeepBook's minimum order.
         const price = async (d, p) => {
-            const a = coinInfo(d, p.coinA), b = coinInfo(d, p.coinB);
+            const flip = isStable(coinInfo(d, p.coinA).symbol) && !isStable(coinInfo(d, p.coinB).symbol);
+            const a = coinInfo(d, flip ? p.coinB : p.coinA), b = coinInfo(d, flip ? p.coinA : p.coinB);
             const amountIn = (10n * 10n ** BigInt(a.decimals)).toString();
-            const q = await quoteSwap(clientFor(d), d, p, p.coinA, amountIn).catch(() => null);
+            const q = await quoteSwap(clientFor(d), d, p, a.type, amountIn).catch(() => null);
             if (!q || q.amountOut === '0')
                 return {};
             const perUnit = (BigInt(q.amountOut) * 10n ** BigInt(a.decimals)) / BigInt(q.amountIn);
@@ -437,10 +442,15 @@ export function createPluginMcp(registry) {
             }))),
             lending: Object.keys(d.protocols.navi.reserves).map((c) => coinInfo(d, c).symbol),
             ...(d.pools.length || Object.keys(d.protocols.navi.reserves).length
-                ? {}
+                ? {
+                    otherCoins: 'These are the coins and pools this package lists, not all it can use. Any other coin the owner holds goes in a transfer or swap rule by its full type; a swap of it also needs, in pools, the id of a DeepBook or Cetus pool holding exactly that pair. The server reads the coin and the pool from chain. Lending stays with the listed coins.',
+                }
                 : {
                     note: 'Transfers and staking only: this network lists no pools and no NAVI reserves, so swap and lending rules are refused here.',
                 }),
+            ...(owner
+                ? { ownerCoins: await readAllHoldings(clientFor(d), d, owner).catch(() => null) }
+                : {}),
         });
         const own = (await exists(path)) ? [await markets(await registry.deployment())] : [];
         const bundled = await Promise.all((await registry.bundledNetworks()).map(async (n) => markets(await registry.bundled(n))));