@mysten-incubation/sui-agent-pass 0.0.0 → 0.1.1

package/dist/mcp.js

@@ -0,0 +1,180 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+import { readFile, stat } from 'node:fs/promises';
+import { sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { clientFor, deepbookSizes, readAllHoldings, readStatus } from './chain.js';
+import { coinInfo } from './domain.js';
+export const result = (value) => ({
+    content: [{ type: 'text', text: JSON.stringify(value) }],
+});
+export const failure = (error, fallback) => ({
+    ...result({ error: error instanceof Error ? error.message : fallback }),
+    isError: true,
+});
+/**
+ * What every client shows the model before any tool call, so a plain request ("sell 0.05 SUI")
+ * is enough: no resource to know about, no project file to read.
+ */
+export const INSTRUCTIONS = [
+    'Sui Agent Pass: an owner authorized this agent key to act on their assets within rules enforced on chain. The owner keeps their coins; you build transactions, this server signs them, and the chain refuses anything outside the rules.',
+    "To act (pay, trade, lend, stake): 1. Call session_info (name the pass if there are several). It returns the rules, what the key may still spend today, the coins with their types and decimals, the pools, the session directory and sdk (install command, import line, and api, the whole SDK surface, so you never need to read the package\'s files). 2. In your working directory run sdk.install once, then write a Node script: sdk.import, `const agent = await Agent.open(directory)`, build the action with a builder (send, swap, supply, withdraw, borrow, repay, stake, unstake) naming the coin type and the amount in base units (units() from the domain module), and `await agent.submit(tx)`. Before a swap, `await quote(identity, pair, amountIn)` and set minOut a little under its amountOut. 3. Read the Outcome: success true means it executed; success false means the chain executed and refused it, and reason is the owner's rule, which you quote; a thrown error means nothing executed, which you never describe as enforcement. 4. Report the digest, what moved and the remaining daily limit from a fresh session_info.",
+    'Never invent amounts or recipients: recipients are the names in the rules, and a missing amount is a question for the owner. After a missing network response, look up the digest before submitting the same action again. Use English for anything the owner reads.',
+    'To set up a pass, change its rules (propose_change, one owner signature, the key stays), size limits, or end it, read agent-pass://playbook; agent-pass://guide documents the SDK and the contract for hand-built transactions.',
+].join(' ');
+/** Where this code runs from: a checkout is installed by path, a published package by name. */
+async function sdkInfo(directory) {
+    const root = fileURLToPath(new URL('..', import.meta.url));
+    const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    const published = root.split(sep).includes('node_modules');
+    return {
+        package: pkg.name,
+        install: published ? `npm install ${pkg.name}@${pkg.version}` : `npm install ${root}`,
+        import: `import { Agent, quote, send, swap, supply, withdraw, borrow, repay, stake, unstake, pickValidator } from '${pkg.name}/agent'`,
+        open: directory ? `await Agent.open(${JSON.stringify(directory)})` : null,
+        // The whole surface, so a script needs nothing from the package's source tree.
+        api: [
+            'Agent.open(directory): Promise<Agent>; agent.identity (pass this to builders); agent.client (SuiGrpcClient for reads); agent.submit(tx, { proveChainRefusal?: boolean }): Promise<Outcome>; agent.close()',
+            'quote(identity, { coinIn, coinOut, poolId?, venue? }, amountIn): Promise<{ pool, amountIn, amountOut }> prices a sale on a listed pool from the venue itself without touching any allowance; amountIn is what the pool would take (DeepBook pays its fee from the input and rounds down to its lot size) and amountOut what comes back. Quote before every swap and set minOut a little under amountOut; never size minOut from a mid price.',
+            'Builders return a Transaction; coins are full type strings (session_info coins lists the ones these rules name, with symbol and decimals) and amounts are base-unit strings: send(identity, coin, amount, recipientName); swap(identity, { coinIn, coinOut, poolId?, venue? }, amountIn, minOut) sells coinIn for coinOut on a listed pool (the first matching pool when none is named); supply(identity, coin, amount) on NAVI, and await withdraw(identity, coin, amount), await borrow(identity, coin, amount), await repay(identity, coin, amount), which first add the oracle price refresh NAVI requires on mainnet; stake(identity, amount, validator) in SUI with validator from await pickValidator(identity); unstake(identity, stakeId); refillGas(identity, amount)',
+            "Outcome: { digest, success, reason (the owner's rule behind a refusal, or null), error, balanceChanges: [{ address, coinType, amount }] }; submit throws when nothing executed",
+            `units(decimal, decimals) from '${pkg.name}/domain' turns "0.05" into base units; each coin's decimals are in session_info coins`,
+        ],
+        note: published ? null : `${root} must be built (npm run build) before installing from it`,
+    };
+}
+/** Which code answers: the package version and when it was built, so a stale server shows. */
+async function serverInfo() {
+    const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    const built = await stat(fileURLToPath(import.meta.url)).then((s) => s.mtime.toISOString());
+    return {
+        version: pkg.version,
+        builtAt: built,
+        note: 'This process keeps the code it started with. After this package is rebuilt or upgraded, restart the agent client so it starts a new server; compare builtAt.',
+    };
+}
+/**
+ * The pools a session may trade on, each with the coins it sells either way and, for DeepBook,
+ * the order sizes the pool enforces: an order under `minSize` fills nothing.
+ */
+export async function venues(client, d) {
+    return Promise.all(d.pools.map(async (pool) => {
+        const sizes = pool.venue === 'deepbook' ? await deepbookSizes(client, d, pool).catch(() => null) : null;
+        const base = coinInfo(d, pool.coinA).symbol, quote = coinInfo(d, pool.coinB).symbol;
+        return {
+            venue: pool.venue,
+            poolId: pool.poolId,
+            coinA: pool.coinA,
+            coinB: pool.coinB,
+            pair: `${base}/${quote}`,
+            entries: pool.venue === 'deepbook'
+                ? {
+                    [`${base}→${quote}`]: 'pass::deepbook_base_to_quote',
+                    [`${quote}→${base}`]: 'pass::deepbook_quote_to_base',
+                }
+                : {
+                    [`${base}→${quote}`]: 'pass::cetus_a_to_b',
+                    [`${quote}→${base}`]: 'pass::cetus_b_to_a',
+                },
+            typeArguments: [pool.coinA, pool.coinB],
+            objects: pool.venue === 'deepbook' ? [pool.poolId] : [d.protocols.cetus.configId, pool.poolId],
+            ...(sizes
+                ? {
+                    minSize: sizes.minSize,
+                    lotSize: sizes.lotSize,
+                    note: `DeepBook pays its taker fee out of the input and then rounds the order down to lotSize; anything under minSize after that fills nothing and the pass refuses it. Sell at least minSize + lotSize (${(BigInt(sizes.minSize) + BigInt(sizes.lotSize)).toString()} base units of ${base}) and let quote() tell you the fill. A Cetus pool takes any size when the rules list one.`,
+                }
+                : {}),
+        };
+    }));
+}
+/**
+ * Everything an agent needs to act: identity, live rules and usage, connection details and the
+ * SDK. `directory` is the session directory when the server knows it, for `Agent.open`.
+ */
+export async function sessionInfo(identity, directory = null) {
+    const { deployment: d, active, sessionAddress } = identity;
+    const client = clientFor(d);
+    const [status, sdk, venueList, server, ownerCoins] = await Promise.all([
+        readStatus(client, d, active, sessionAddress),
+        sdkInfo(directory),
+        venues(client, d),
+        serverInfo(),
+        readAllHoldings(client, d, active.owner).catch(() => null),
+    ]);
+    return {
+        ...identity,
+        ...status,
+        ...(directory ? { directory } : {}),
+        server,
+        sdk,
+        coins: d.coins,
+        // Everything the owner holds, so an agent can see a coin the rules do not cover yet; only
+        // listed coins can appear in rules, since a rule names a coin's pools and reserves.
+        ownerCoins,
+        venues: venueList,
+        transactionGuide: `Write a Node script: ${sdk.install}, then ${sdk.import}; open the session with Agent.open(directory) and submit(tx) a builder's transaction. submit signs through this server, executes on Sui and returns the persisted outcome (success, reason, error, balanceChanges); it throws when nothing executed. For a PTB the builders do not cover: funds are in the owner's address balance ${active.owner}; every entry takes the pass object then the shared config ${d.configId}, and each spend adds a tx.withdrawal({ from: "allowance", allowance, funder, amount, type }) input and the allowance object as a mutable shared input; calls go to ${d.publishedAt}::pass; sender and gas owner ${sessionAddress}. Read resource agent-pass://guide for the SDK and the complete contract API.`,
+        limits: [
+            "ownerBalances splits each coin into addressBalance and coinBalance. Allowances draw from the owner's address balance only; their coin objects are out of reach but still theirs, so a low address balance next to coin objects is not an owner who is out of money. The owner's own transactions can pay gas from either side.",
+            'Gas stipend is freely controllable by this key; the gas allowance tops it up within its own cap.',
+            "Every action needs an installed policy for its coin type; recipients are named, swaps run only on listed pools, lending keeps the health factor above the owner's floor, stakes go to listed validators (or any active one when the list is empty) and stay in the pass.",
+        ],
+    };
+}
+export const SIGN_DESCRIPTION = 'Sign full base64 Sui TransactionData constructed by you. Does not build, simulate, approve, or execute trades. A signature is NOT evidence that the policies permit the transaction; the chain enforces them. Never submit the same financial action again merely because a network response is missing; inspect its digest first.';
+export const SIGN_ANNOTATIONS = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+/** The two documents every client can read: the playbook for conduct, the guide for the API. */
+export function registerDocs(server) {
+    const docs = [
+        {
+            name: 'playbook',
+            file: 'PLAYBOOK.md',
+            description: 'How to turn a request into rules, get the signature, act within the rules, report and revoke',
+        },
+        {
+            name: 'transaction-guide',
+            file: 'AGENT.md',
+            description: 'Complete contract interface and agent-side construction examples',
+        },
+    ];
+    for (const doc of docs)
+        server.registerResource(doc.name, `agent-pass://${doc.name === 'transaction-guide' ? 'guide' : doc.name}`, { description: doc.description, mimeType: 'text/markdown' }, async (uri) => ({
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: 'text/markdown',
+                    text: await readFile(new URL(`../docs/${doc.file}`, import.meta.url), 'utf8'),
+                },
+            ],
+        }));
+}
+/** The single-session server behind the authenticated HTTP transport. */
+export function createMcp(identity, signer, directory = null) {
+    const server = new McpServer({ name: 'sui-agent-pass', version: '0.1.0' }, { instructions: INSTRUCTIONS });
+    registerDocs(server);
+    server.registerTool('session_info', {
+        description: "Read the pass's installed policies with their live usage, the owner's balances and allowances, the agent term, protocol object IDs, Sui connection details and the SDK install command. Act with a Node script against the SDK, which signs here and submits to Sui itself; or build your own PTB, call sign_transaction and submit the returned bytes and signature yourself.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => result(await sessionInfo(identity, directory)));
+    server.registerTool('sign_transaction', {
+        description: SIGN_DESCRIPTION,
+        inputSchema: { transactionBytes: z.string().min(1).max(180_000) },
+        annotations: SIGN_ANNOTATIONS,
+    }, async ({ transactionBytes }) => {
+        try {
+            return result(await signer.sign(transactionBytes));
+        }
+        catch (error) {
+            return failure(error, 'Signing failed');
+        }
+    });
+    return server;
+}

package/dist/navi.js

@@ -0,0 +1,125 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * What both sides of the product need to know about NAVI: the oracle refresh every
+ * health-checked action must carry on mainnet, a position's balances, and emptying a position
+ * into its owner's wallet. NAVI's app works on wallet addresses, not on account-cap positions,
+ * so a cap the owner holds is only useful through code like this.
+ */
+import { bcs } from '@mysten/sui/bcs';
+import { Transaction, } from '@mysten/sui/transactions';
+import { normalizeStructTag, normalizeSuiAddress, parseStructTag } from '@mysten/sui/utils';
+import { getPriceFeeds, updateOraclePricesPTB } from '@naviprotocol/lending';
+import { clientFor, naviAccountOwner } from './chain.js';
+import { sameCoin } from './domain.js';
+const CLOCK = '0x6';
+const SUI_SYSTEM = '0x5';
+/**
+ * NAVI values a position at oracle prices no older than its update interval, so every action
+ * that checks health first refreshes the prices of the reserves this deployment lends, the way
+ * NAVI's own clients do: Pyth updates through Wormhole, then `oracle_pro::update_single_price_v2`.
+ * NAVI's SDK carries the feed configuration and fetches it live, so an oracle upgrade on their
+ * side needs no change here. The stand-ins off mainnet keep fixed prices and have nothing to
+ * refresh.
+ */
+export async function refreshNaviPrices(tx, d) {
+    if (d.network !== 'mainnet')
+        return;
+    const lent = Object.keys(d.protocols.navi.reserves);
+    const feeds = (await getPriceFeeds({ env: 'prod' })).filter((f) => lent.some((coin) => sameCoin(coin, f.coinType)));
+    await updateOraclePricesPTB(tx, feeds, {
+        env: 'prod',
+        client: clientFor(d),
+        updatePythPriceFeeds: true,
+    });
+}
+/** Reads a position's collateral and debt in every reserve this deployment lends, by simulation. */
+export async function readNaviPosition(client, d, user) {
+    const n = d.protocols.navi, reserves = Object.entries(n.reserves);
+    const tx = new Transaction();
+    tx.setSender(normalizeSuiAddress('0x1'));
+    for (const [, r] of reserves)
+        for (const view of ['user_collateral_balance', 'user_loan_balance'])
+            tx.moveCall({
+                target: `${n.publishedAt}::logic::${view}`,
+                arguments: [tx.object(n.storageId), tx.pure.u8(r.assetId), tx.pure.address(user)],
+            });
+    const result = await client.simulateTransaction({
+        transaction: tx,
+        include: { commandResults: true },
+    });
+    const executed = result.$kind === 'Transaction' ? result.Transaction : result.FailedTransaction;
+    if (!executed?.status.success)
+        throw new Error(executed?.status.error?.message ?? 'Could not read the NAVI position');
+    const value = (i) => {
+        const v = result.commandResults?.[i]?.returnValues?.[0]?.bcs;
+        return v ? bcs.u256().parse(v) : '0';
+    };
+    const position = { collateral: {}, debt: {} };
+    reserves.forEach(([coin], i) => {
+        const c = value(2 * i), l = value(2 * i + 1);
+        if (c !== '0')
+            position.collateral[normalizeStructTag(coin)] = c;
+        if (l !== '0')
+            position.debt[normalizeStructTag(coin)] = l;
+    });
+    return position;
+}
+/**
+ * Withdraws every collateral balance of a position into `owner`'s wallet, through the cap. NAVI
+ * caps a withdrawal at the user's balance but first checks the request against the reserve's
+ * free liquidity, so the request is the balance read a moment ago plus a small margin for the
+ * interest since: everything comes out, and the request stays well inside the liquidity. A
+ * position with debt cannot be emptied: NAVI would refuse the health check, so callers skip the
+ * sweep and hand the cap over instead. `refreshNaviPrices` must precede this in the transaction.
+ */
+export function withdrawAllInto(tx, d, cap, position, owner) {
+    const n = d.protocols.navi, coins = [];
+    for (const [coin, r] of Object.entries(n.reserves)) {
+        const have = position.collateral[normalizeStructTag(coin)];
+        if (!have)
+            continue;
+        const request = (BigInt(have) + BigInt(have) / 1000n + 1n).toString();
+        const balance = tx.moveCall({
+            target: `${n.publishedAt}::incentive_v3::withdraw_with_account_cap_v2`,
+            typeArguments: [coin],
+            arguments: [
+                tx.object(CLOCK),
+                tx.object(n.oracleId),
+                tx.object(n.storageId),
+                tx.object(r.poolId),
+                tx.pure.u8(r.assetId),
+                tx.pure.u64(request),
+                tx.object(n.incentiveV2Id),
+                tx.object(n.incentiveV3Id),
+                cap,
+                tx.object(SUI_SYSTEM),
+            ],
+        });
+        coins.push(tx.moveCall({
+            target: '0x2::coin::from_balance',
+            typeArguments: [coin],
+            arguments: [balance],
+        }));
+    }
+    if (coins.length)
+        tx.transferObjects(coins, owner);
+}
+/** Whether a position can be emptied in one go: something to withdraw and nothing owed. */
+export const canSweep = (p) => !!p && Object.keys(p.collateral).length > 0 && Object.keys(p.debt).length === 0;
+/** NAVI account caps an address holds, with the position each controls. */
+export async function naviCapsOf(client, d, owner) {
+    const wanted = `${normalizeSuiAddress(d.protocols.navi.packageId)}::account::AccountCap`;
+    const found = [];
+    let cursor = null;
+    do {
+        const page = await client.listOwnedObjects({ owner, cursor, limit: 50, include: { content: true } });
+        for (const o of page.objects) {
+            const tag = parseStructTag(o.type);
+            if (`${normalizeSuiAddress(tag.address)}::${tag.module}::${tag.name}` === wanted && o.content)
+                found.push({ capId: o.objectId, user: naviAccountOwner(o.content) });
+        }
+        cursor = page.hasNextPage ? page.cursor : null;
+    } while (cursor && found.length < 200);
+    return found;
+}