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

package/dist/agent.js

@@ -0,0 +1,409 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The agent SDK: construction against the pass, signing through the session signer, submission
+ * and the persisted outcome. Importable as `@mysten-incubation/sui-agent-pass/agent`; never imported by the
+ * signing service.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { Inputs, Transaction } from '@mysten/sui/transactions';
+import { fromBase64, normalizeStructTag, normalizeSuiAddress, toBase64 } from '@mysten/sui/utils';
+import { activeValidators, clientFor, quoteSwap, readAllowance, readControl } from './chain.js';
+import { describeRefusal } from './describe.js';
+import { poolsFor, sameCoin, SUI, } from './domain.js';
+import { refreshNaviPrices } from './navi.js';
+const CLOCK = '0x6';
+const SUI_SYSTEM = '0x5';
+/**
+ * The session's own gas float only has to cover the next transaction, whose budget the build
+ * estimates. The float is refilled from the gas allowance when it falls under the floor, by as
+ * much as the allowance can still give up to one top-up, so a small gas allowance still works;
+ * a transaction costs well under 0.01 SUI on mainnet.
+ */
+const GAS_FLOOR = 10000000n;
+const GAS_TOPUP = 50000000n;
+/** Below this the next transaction may not even pay for itself. */
+const GAS_RESERVE = 2000000n;
+/** A build without simulation has nothing to estimate its budget; this covers any pass action. */
+const PROVE_BUDGET = 20_000_000;
+export class Agent {
+    mcp;
+    identity;
+    client;
+    constructor(mcp, identity) {
+        this.mcp = mcp;
+        this.identity = identity;
+        this.client = clientFor(identity.deployment);
+    }
+    /** Connects through the session directory `session_info` names: its signer URL and token. */
+    static async open(directory) {
+        const [runtime, token] = await Promise.all([
+            readFile(join(directory, 'runtime.json'), 'utf8').then(JSON.parse),
+            readFile(join(directory, 'mcp.token'), 'utf8'),
+        ]);
+        return Agent.connect(runtime.mcpUrl, token.trim());
+    }
+    static async connect(url, bearer) {
+        const client = new Client({ name: 'independent-agent', version: '0.1.0' });
+        await client.connect(new StreamableHTTPClientTransport(new URL(url), {
+            requestInit: { headers: { Authorization: `Bearer ${bearer}` } },
+        }));
+        const info = await client.callTool({ name: 'session_info', arguments: {} });
+        if (info.isError)
+            throw new Error(JSON.stringify(info));
+        return new Agent(client, JSON.parse(info.content[0].text));
+    }
+    async submit(tx, options = {}) {
+        await this.ensureGas();
+        return this.execute(tx, options);
+    }
+    async close() {
+        await this.mcp.close();
+    }
+    /** Tops up the session's own gas float from the gas allowance before it runs dry. A refused
+     * refill (cap or window hit, owner balance empty) is not fatal while the float still covers one
+     * budget: it is reported and the action proceeds on what is left. */
+    async float() {
+        const { sessionAddress, deployment } = this.identity;
+        const { balance } = await this.client.getBalance({ owner: sessionAddress, coinType: SUI });
+        return BigInt(balance.addressBalance);
+    }
+    async ensureGas() {
+        const float = await this.float();
+        if (float >= GAS_FLOOR)
+            return;
+        const { deployment, active } = this.identity;
+        // What the gas allowance can still give: under its lifetime cap and its current window.
+        const view = await readAllowance(this.client, active.gasAllowance, SUI);
+        const room = [
+            view?.lifetimeCap === null || view?.lifetimeCap === undefined
+                ? null
+                : BigInt(view.lifetimeCap) - BigInt(view.currentSpend),
+            view?.rateLimit ? BigInt(view.rateLimit.limit) - BigInt(view.rateLimit.spentNow) : null,
+        ].filter((r) => r !== null);
+        const available = view ? room.reduce((m, r) => (r < m ? r : m), GAS_TOPUP) : 0n;
+        const stranded = () => new Error(`The session holds ${float} MIST for gas and the gas allowance has nothing left to give`);
+        if (available <= 0n) {
+            if (float < GAS_RESERVE)
+                throw stranded();
+            return;
+        }
+        try {
+            await this.execute(refillGas(this.identity, available.toString()));
+        }
+        catch (error) {
+            if (float < GAS_RESERVE)
+                throw error;
+            console.warn(`Gas refill refused, continuing on the remaining float: ${error.message}`);
+        }
+    }
+    async execute(tx, options = {}) {
+        const client = this.client;
+        tx.setSender(this.identity.sessionAddress);
+        tx.setGasOwner(this.identity.sessionAddress);
+        tx.setGasPayment([]);
+        // The simulated build estimates the budget; the other path gets a fixed one the float can pay.
+        const bytes = options.proveChainRefusal
+            ? await buildWithoutSimulation(tx, this.identity, Math.min(PROVE_BUDGET, Number(await this.float())))
+            : await tx.build({ client });
+        const reply = await this.mcp.callTool({
+            name: 'sign_transaction',
+            arguments: { transactionBytes: toBase64(bytes) },
+        });
+        if (reply.isError)
+            throw new Error(`Signer refused: ${JSON.stringify(reply.content)}`);
+        const signed = JSON.parse(reply.content[0].text);
+        const result = await client.executeTransaction({
+            transaction: fromBase64(signed.bytes),
+            signatures: [signed.signature],
+            include: { effects: true, events: true, balanceChanges: true },
+        });
+        await client.waitForTransaction({ result });
+        const record = result.Transaction ?? result.FailedTransaction;
+        return {
+            digest: signed.digest,
+            success: record.status.success,
+            error: record.status.error ?? null,
+            reason: record.status.success
+                ? null
+                : describeRefusal(this.identity.deployment, record.status.error, null),
+            balanceChanges: (record.balanceChanges ?? []).map((c) => ({
+                address: c.address,
+                coinType: c.coinType,
+                amount: c.amount,
+            })),
+            signed,
+            result,
+        };
+    }
+}
+/** The first validator the owner listed, or the first active one when the list is empty. */
+export async function pickValidator(i) {
+    const client = clientFor(i.deployment);
+    const listed = (await readControl(client, i.deployment, i.active.passId)).policies.staking[0]
+        ?.validators;
+    const validator = listed?.[0] ?? (await activeValidators(client))[0];
+    if (!validator)
+        throw new Error('No validator to stake with');
+    return validator;
+}
+/** Pull SUI from the dedicated gas allowance into the session's own address to pay gas. */
+export function refillGas(i, amount) {
+    const d = i.deployment, tx = new Transaction(), active = i.active;
+    const balance = tx.moveCall({
+        target: '0x2::allowance::balance_spend',
+        typeArguments: [SUI],
+        arguments: [
+            tx.object(active.gasAllowance),
+            tx.withdrawal({
+                amount,
+                type: SUI,
+                from: 'allowance',
+                allowance: active.gasAllowance,
+                funder: active.owner,
+            }),
+            tx.object(CLOCK),
+        ],
+    });
+    tx.moveCall({
+        target: '0x2::balance::send_funds',
+        typeArguments: [SUI],
+        arguments: [balance, tx.pure.address(i.sessionAddress)],
+    });
+    return tx;
+}
+/** Explicit proof path: resolve references and gas metadata without executing a dry run.
+ * The normal gRPC SDK builder simulates and refuses failed transactions before signing.
+ * These examples use only owned/shared object arguments (no Receiving arguments).
+ */
+export async function buildWithoutSimulation(tx, i, budget = PROVE_BUDGET) {
+    const client = clientFor(i.deployment), { systemState } = await client.getCurrentSystemState();
+    tx.setSender(i.sessionAddress);
+    tx.setGasOwner(i.sessionAddress);
+    tx.setGasPayment([]);
+    tx.setGasPrice(systemState.referenceGasPrice);
+    tx.setGasBudget(budget);
+    tx.setExpiration({
+        ValidDuring: {
+            minEpoch: systemState.epoch,
+            maxEpoch: String(BigInt(systemState.epoch) + 1n),
+            minTimestamp: null,
+            maxTimestamp: null,
+            chain: i.deployment.chainIdentifier,
+            nonce: crypto.getRandomValues(new Uint32Array(1))[0],
+        },
+    });
+    tx.addBuildPlugin(async (data, _options, next) => {
+        await Promise.all(data.inputs.map(async (input, index) => {
+            if (!input.UnresolvedObject)
+                return;
+            const { object } = await client.getObject({
+                objectId: input.UnresolvedObject.objectId,
+            });
+            data.inputs[index] =
+                object.owner.$kind === 'Shared'
+                    ? Inputs.SharedObjectRef({
+                        objectId: object.objectId,
+                        initialSharedVersion: object.owner.Shared.initialSharedVersion,
+                        mutable: object.objectId !== normalizeSuiAddress('0x6'),
+                    })
+                    : Inputs.ObjectRef(object);
+        }));
+        await next();
+    });
+    return tx.build();
+}
+/**
+ * Every spend draws from the owner's allowance for that coin: the allowance object as a mutable
+ * shared input plus a withdrawal input for the amount.
+ */
+function funds(tx, i, coin, amount) {
+    const ids = i.active.allowances[normalizeStructTag(coin)];
+    if (!ids)
+        throw new Error(`This pass has no allowance for ${coin}`);
+    return [
+        tx.object(ids.allowance),
+        tx.withdrawal({
+            amount,
+            type: coin,
+            from: 'allowance',
+            allowance: ids.allowance,
+            funder: i.active.owner,
+        }),
+    ];
+}
+const pass = (tx, i) => [
+    tx.object(i.active.passId),
+    tx.object(i.deployment.configId),
+];
+/** Direct transfer of a coin to a recipient the owner named. Amount in the coin's base units. */
+export function send(i, coin, amount, recipient) {
+    const d = i.deployment, tx = new Transaction();
+    tx.moveCall({
+        target: `${d.publishedAt}::pass::transfer`,
+        typeArguments: [coin],
+        arguments: [
+            ...pass(tx, i),
+            ...funds(tx, i, coin, amount),
+            tx.pure.string(recipient),
+            tx.object(CLOCK),
+        ],
+    });
+    return tx;
+}
+/** The listed pool for a pair, narrowed by id or venue; the first listed one by default. */
+function poolFor(i, pair) {
+    const pool = poolsFor(i.deployment, pair.coinIn, pair.coinOut).find((p) => (!pair.poolId || p.poolId === pair.poolId) && (!pair.venue || p.venue === pair.venue));
+    if (!pool)
+        throw new Error(`No listed pool sells ${pair.coinIn} for ${pair.coinOut}`);
+    return pool;
+}
+/**
+ * What a sale would return right now, from the venue's own quote and touching no allowance:
+ * `amountIn` is what the pool would actually take (DeepBook pays its fee from the input and
+ * rounds down to the lot size, so a small order fills nothing) and `amountOut` what comes back.
+ * Size `minOut` from this, a little under `amountOut`, rather than from a mid price.
+ */
+export async function quote(i, pair, amountIn) {
+    const pool = poolFor(i, pair);
+    const result = await quoteSwap(clientFor(i.deployment), i.deployment, pool, pair.coinIn, amountIn);
+    return { pool, ...result };
+}
+/**
+ * Sells `coinIn` for `coinOut` on a listed pool. Proceeds return to the owner, never to the
+ * agent. The pool decides the entry and its direction: DeepBook base to quote or quote to base,
+ * Cetus a to b or b to a. Without `poolId`, the first listed pool for the pair.
+ */
+export function swap(i, pair, amountIn, minOut) {
+    const d = i.deployment, tx = new Transaction();
+    const pool = poolFor(i, pair);
+    const forward = sameCoin(pool.coinA, pair.coinIn);
+    const entry = pool.venue === 'deepbook'
+        ? forward
+            ? 'deepbook_base_to_quote'
+            : 'deepbook_quote_to_base'
+        : forward
+            ? 'cetus_a_to_b'
+            : 'cetus_b_to_a';
+    const market = pool.venue === 'deepbook'
+        ? [tx.object(pool.poolId)]
+        : [tx.object(d.protocols.cetus.configId), tx.object(pool.poolId)];
+    tx.moveCall({
+        target: `${d.publishedAt}::pass::${entry}`,
+        typeArguments: [pool.coinA, pool.coinB],
+        arguments: [
+            ...pass(tx, i),
+            ...funds(tx, i, pair.coinIn, amountIn),
+            ...market,
+            tx.pure.u64(minOut),
+            tx.object(CLOCK),
+        ],
+    });
+    return tx;
+}
+const reserve = (i, coin) => {
+    const r = i.deployment.protocols.navi.reserves[normalizeStructTag(coin)];
+    if (!r)
+        throw new Error(`NAVI has no reserve for ${coin} in this deployment`);
+    return r;
+};
+/** Supply a coin to NAVI as collateral for the pass's own position. */
+export function supply(i, coin, amount) {
+    const d = i.deployment, tx = new Transaction(), n = d.protocols.navi, r = reserve(i, coin);
+    tx.moveCall({
+        target: `${d.publishedAt}::pass::navi_supply`,
+        typeArguments: [coin],
+        arguments: [
+            ...pass(tx, i),
+            ...funds(tx, i, coin, amount),
+            tx.object(n.storageId),
+            tx.object(r.poolId),
+            tx.pure.u8(r.assetId),
+            tx.object(n.incentiveV2Id),
+            tx.object(n.incentiveV3Id),
+            tx.object(CLOCK),
+        ],
+    });
+    return tx;
+}
+/** Withdraw supplied collateral from NAVI into the owner's balance. No allowance is drawn. */
+export function withdraw(i, coin, amount) {
+    return naviAmount(i, 'navi_withdraw', coin, amount);
+}
+/** Borrow a coin against the position, into the owner's balance. No allowance is drawn. */
+export function borrow(i, coin, amount) {
+    return naviAmount(i, 'navi_borrow', coin, amount);
+}
+async function naviAmount(i, entry, coin, amount) {
+    const d = i.deployment, tx = new Transaction(), n = d.protocols.navi, r = reserve(i, coin);
+    await refreshNaviPrices(tx, d);
+    // NAVI's SUI pool stakes idle SUI and may unstake to pay out, hence the system state.
+    tx.moveCall({
+        target: `${d.publishedAt}::pass::${entry}_v2`,
+        typeArguments: [coin],
+        arguments: [
+            ...pass(tx, i),
+            tx.object(n.oracleId),
+            tx.object(n.storageId),
+            tx.object(r.poolId),
+            tx.pure.u8(r.assetId),
+            tx.object(n.incentiveV2Id),
+            tx.object(n.incentiveV3Id),
+            tx.object(SUI_SYSTEM),
+            tx.pure.u64(amount),
+            tx.object(CLOCK),
+        ],
+    });
+    return tx;
+}
+/**
+ * Repay NAVI debt from the owner's allowance. The allowance is charged in full before NAVI
+ * runs: size it from the live debt, since an over-payment returns to the owner but still counts.
+ */
+export async function repay(i, coin, amount) {
+    const d = i.deployment, tx = new Transaction(), n = d.protocols.navi, r = reserve(i, coin);
+    await refreshNaviPrices(tx, d);
+    tx.moveCall({
+        target: `${d.publishedAt}::pass::navi_repay`,
+        typeArguments: [coin],
+        arguments: [
+            ...pass(tx, i),
+            ...funds(tx, i, coin, amount),
+            tx.object(n.oracleId),
+            tx.object(n.storageId),
+            tx.object(r.poolId),
+            tx.pure.u8(r.assetId),
+            tx.object(n.incentiveV2Id),
+            tx.object(n.incentiveV3Id),
+            tx.object(CLOCK),
+        ],
+    });
+    return tx;
+}
+/** Stake SUI with a validator; the `StakedSui` stays in the pass. */
+export function stake(i, amount, validator) {
+    const d = i.deployment, tx = new Transaction();
+    tx.moveCall({
+        target: `${d.publishedAt}::pass::stake`,
+        arguments: [
+            ...pass(tx, i),
+            ...funds(tx, i, SUI, amount),
+            tx.object(SUI_SYSTEM),
+            tx.pure.address(validator),
+            tx.object(CLOCK),
+        ],
+    });
+    return tx;
+}
+/** Withdraw one held stake, principal and rewards, into the owner's balance. No allowance is drawn. */
+export function unstake(i, stakeId) {
+    const d = i.deployment, tx = new Transaction();
+    tx.moveCall({
+        target: `${d.publishedAt}::pass::unstake`,
+        arguments: [...pass(tx, i), tx.object(SUI_SYSTEM), tx.pure.id(stakeId), tx.object(CLOCK)],
+    });
+    return tx;
+}