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

package/dist/domain.js

@@ -0,0 +1,393 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+import { fromBase64, isValidSuiAddress, normalizeStructTag, normalizeSuiAddress, toBase64, } from '@mysten/sui/utils';
+import { z } from 'zod';
+/** The gas coin, in the normalized spelling every coin-keyed record uses. */
+export const SUI = normalizeStructTag('0x2::sui::SUI');
+export const DAY_MS = 86_400_000;
+/** NAVI's fixed-point scale for health factors: 1e27 is 1.0. */
+export const RAY = 10n ** 27n;
+export const address = z
+    .string()
+    .refine(isValidSuiAddress, 'Invalid Sui address')
+    .transform((v) => normalizeSuiAddress(v));
+/** A coin's type tag, normalized so two spellings of one coin compare equal. */
+export const coinType = z
+    .string()
+    .regex(/^0x[0-9a-fA-F]+::[A-Za-z_][A-Za-z0-9_]*::[A-Za-z_][A-Za-z0-9_]*(<.*>)?$/, 'Not a coin type')
+    .transform((v) => normalizeStructTag(v));
+export const amount = z
+    .string()
+    .regex(/^(0|[1-9][0-9]*)$/)
+    .refine((v) => BigInt(v) <= 18446744073709551615n, 'Amount exceeds u64');
+const positive = amount.refine((v) => BigInt(v) > 0n, 'Must be positive');
+/** Name of the separate SUI allowance the agent draws on to top up its own gas float. */
+export const AGENT_GAS_NAME = 'agent gas';
+export const sameCoin = (a, b) => normalizeStructTag(a) === normalizeStructTag(b);
+/** The agent names recipients by nickname; it never supplies an address. */
+export const recipientName = z.string().regex(/^[a-z0-9_-]{1,32}$/);
+const perAndDaily = (r) => BigInt(r.perX) <= BigInt(r.daily);
+/** `TransferPolicy<coin>`: sends of one coin to named recipients. Base units of that coin. */
+export const TransferRulesSchema = z
+    .object({
+    coin: coinType,
+    recipients: z.array(z.object({ name: recipientName, address }).strict()).min(1),
+    perTransfer: positive,
+    daily: positive,
+})
+    .strict()
+    .refine((r) => perAndDaily({ perX: r.perTransfer, daily: r.daily }) &&
+    new Set(r.recipients.map((x) => x.name)).size === r.recipients.length, 'Per-transfer limit must not exceed the daily limit; recipient names must be unique');
+export const VenueSchema = z.enum(['deepbook', 'cetus']);
+/**
+ * `SwapPolicy<coinIn, coinOut>`: selling `coinIn` for `coinOut` on the listed pools. Limits in
+ * `coinIn` base units; `minPrice` is `coinOut` base units per 1e9 base units of `coinIn`, the
+ * policy's own scale (`priceUnits` converts a human price).
+ */
+export const SwapRulesSchema = z
+    .object({
+    coinIn: coinType,
+    coinOut: coinType,
+    /** Pool object IDs, from the deployment's pools for this pair. */
+    pools: z.array(address).min(1),
+    perTrade: positive,
+    daily: positive,
+    /** Required on chain too: the agent key builds the whole transaction and can move a pool's
+     * price inside it, so without a floor the daily cap could be sold for nothing. */
+    minPrice: positive,
+})
+    .strict()
+    .refine((r) => perAndDaily({ perX: r.perTrade, daily: r.daily }) &&
+    !sameCoin(r.coinIn, r.coinOut) &&
+    new Set(r.pools).size === r.pools.length, 'Per-trade limit must not exceed the daily limit; the pair must differ; pools must be unique');
+/**
+ * `LendingPolicy<coin>` on NAVI: supplying and withdrawing one coin, and when `allowBorrow`,
+ * borrowing and repaying it. The health factor floor applies to any withdraw or borrow under
+ * this policy; null means no floor.
+ */
+export const LendingRulesSchema = z
+    .object({
+    coin: coinType,
+    allowBorrow: z.boolean(),
+    perAction: positive,
+    daily: positive,
+    minHealthFactor: z.number().min(1).max(100).nullable(),
+})
+    .strict()
+    .refine((r) => perAndDaily({ perX: r.perAction, daily: r.daily }), 'Per-action limit must not exceed the daily limit');
+/** `StakingPolicy`: staking SUI with validators. SUI base units; the system's 1 SUI minimum applies. */
+export const StakingRulesSchema = z
+    .object({
+    /** Validator addresses the agent may stake with; empty allows any active validator. */
+    validators: z.array(address),
+    perStake: positive,
+    daily: positive,
+})
+    .strict()
+    .refine((r) => perAndDaily({ perX: r.perStake, daily: r.daily }) &&
+    new Set(r.validators).size === r.validators.length, 'Per-stake limit must not exceed the daily limit; validators must be unique');
+const unique = (keys) => new Set(keys).size === keys.length;
+/**
+ * Each rule becomes one on-chain policy object, keyed by its type: one transfer rule per coin,
+ * one swap rule per direction, one lending rule per coin, at most one staking rule. An action
+ * with no rule for its coin is refused.
+ */
+export const PolicySchema = z
+    .object({
+    transfers: z.array(TransferRulesSchema).default([]),
+    swaps: z.array(SwapRulesSchema).default([]),
+    lending: z.array(LendingRulesSchema).default([]),
+    staking: StakingRulesSchema.nullable().default(null),
+})
+    .strict()
+    .refine((p) => p.transfers.length || p.swaps.length || p.lending.length || p.staking, 'Allow at least one kind of action')
+    .refine((p) => unique(p.transfers.map((t) => t.coin)) &&
+    unique(p.swaps.map((s) => `${s.coinIn}>${s.coinOut}`)) &&
+    unique(p.lending.map((l) => l.coin)), 'One transfer rule per coin, one swap rule per direction, one lending rule per coin');
+/** The system's own minimum for one stake. */
+export const MIN_STAKE = '1000000000';
+/** The coins a rule set draws from the owner's address balance: what needs an allowance. */
+export function spentCoins(p) {
+    const coins = [
+        ...p.transfers.map((t) => t.coin),
+        ...p.swaps.map((s) => s.coinIn),
+        // Supplying draws the coin; so does repaying when borrowing is allowed.
+        ...p.lending.map((l) => l.coin),
+        ...(p.staking ? [SUI] : []),
+    ];
+    return [...new Set(coins.map((c) => normalizeStructTag(c)))];
+}
+const CoinSchema = z
+    .object({
+    type: coinType,
+    symbol: z.string().min(1).max(16),
+    decimals: z.number().int().min(0).max(18),
+    /** Added from the chain's own metadata for a proposal, not vetted in the deployment: shown with its type. */
+    unlisted: z.boolean().optional(),
+})
+    .strict();
+/** A pool the pass can trade on. `coinA`/`coinB` is the pool's own order: DeepBook base and quote, Cetus A and B. */
+const PoolSchema = z
+    .object({ venue: VenueSchema, poolId: address, coinA: coinType, coinB: coinType })
+    .strict();
+const assetIndex = z.number().int().min(0).max(255);
+export const DeploymentSchema = z
+    .object({
+    network: z.enum(['localnet', 'testnet', 'devnet', 'mainnet']),
+    grpcUrl: z.string().url(),
+    chainIdentifier: z.string().min(1),
+    /** The original package: every type of the pass is addressed by it. */
+    packageId: address,
+    /** The latest upgrade of that package: every call goes to it. Equal until an upgrade. */
+    publishedAt: address,
+    /** The package's shared `Config`: the version gate every spend and install checks. */
+    configId: address,
+    /**
+     * Where the owner reviews and signs: the site we host at a fixed origin, built with this
+     * deployment. Absent in development, when the local process serves the same build.
+     */
+    siteUrl: z.string().url().optional(),
+    /** The coins a pass on this chain can hold rules for. SUI, the gas coin, comes first. */
+    coins: z.array(CoinSchema).min(1),
+    /** The pools a swap rule can list, in either direction. */
+    pools: z.array(PoolSchema),
+    /** A demo stablecoin's faucet, which the authorization mints from instead of converting coins. */
+    demoFaucet: z
+        .object({ packageId: address, faucetId: address, coin: coinType })
+        .strict()
+        .optional(),
+    /** Protocol packages and objects on this chain. Stand-ins off mainnet. */
+    protocols: z
+        .object({
+        deepbook: z
+            .object({
+            packageId: address,
+            /** The latest upgrade, for calls made from a PTB; the original is version-gated. */
+            publishedAt: address,
+        })
+            .strict(),
+        /** `packageId` defines the pool type; `publishedAt` is the upgrade that answers calls. */
+        cetus: z.object({ packageId: address, publishedAt: address, configId: address }).strict(),
+        navi: z
+            .object({
+            /** The package that defines `account::AccountCap`, which the pass holds. */
+            packageId: address,
+            /** The latest upgrade of the lending package, which answers calls. */
+            publishedAt: address,
+            oraclePackageId: address,
+            storageId: address,
+            oracleId: address,
+            incentiveV2Id: address,
+            incentiveV3Id: address,
+            /** NAVI's pool object and asset index per coin a lending rule can name. */
+            reserves: z.record(coinType, z.object({ poolId: address, assetId: assetIndex }).strict()),
+        })
+            .strict(),
+    })
+        .strict(),
+})
+    .strict()
+    .refine((d) => sameCoin(d.coins[0].type, SUI), 'The first coin must be SUI, the gas coin')
+    .refine((d) => unique(d.coins.map((c) => c.type)), 'Each coin once')
+    .refine((d) => d.pools.every((p) => d.coins.some((c) => sameCoin(c.type, p.coinA)) &&
+    d.coins.some((c) => sameCoin(c.type, p.coinB))) &&
+    Object.keys(d.protocols.navi.reserves).every((t) => d.coins.some((c) => sameCoin(c.type, t))) &&
+    (!d.demoFaucet || d.coins.some((c) => sameCoin(c.type, d.demoFaucet.coin))), 'Pools, reserves and the demo faucet may only name listed coins');
+/** A listed coin's symbol and decimals, by type. */
+export function coinInfo(d, type) {
+    const c = d.coins.find((x) => sameCoin(x.type, type));
+    if (!c)
+        throw new Error(`${type} is not a coin this deployment lists`);
+    return c;
+}
+/** A listed coin by symbol, case-insensitive, for inputs written in human terms. */
+export function coinBySymbol(d, symbol) {
+    const c = d.coins.find((x) => x.symbol.toLowerCase() === symbol.toLowerCase());
+    if (!c)
+        throw new Error(`No coin called ${symbol}; this deployment lists ${d.coins.map((x) => x.symbol).join(', ')}`);
+    return c;
+}
+/** The pools that trade `coinIn` for `coinOut`, in either pool order. */
+export function poolsFor(d, coinIn, coinOut) {
+    return d.pools.filter((p) => (sameCoin(p.coinA, coinIn) && sameCoin(p.coinB, coinOut)) ||
+        (sameCoin(p.coinB, coinIn) && sameCoin(p.coinA, coinOut)));
+}
+/**
+ * What a local process hands the site in the URL, and all it ever hands it: the rules the owner
+ * is about to sign and the agent key they are for. The site reads the rest from the chain.
+ */
+export const ProposalSchema = z
+    .object({
+    v: z.literal(1),
+    sessionAddress: address,
+    setup: z.lazy(() => SetupSchema),
+    /** Present when the proposal changes the rules of this existing pass instead of creating one. */
+    passId: address.optional(),
+})
+    .strict();
+export const encodeProposal = (p) => toBase64(new TextEncoder().encode(JSON.stringify(ProposalSchema.parse(p))))
+    .replaceAll('+', '-')
+    .replaceAll('/', '_')
+    .replace(/=+$/, '');
+export const decodeProposal = (s) => ProposalSchema.parse(JSON.parse(new TextDecoder().decode(fromBase64(s.replaceAll('-', '+').replaceAll('_', '/')))));
+const ttlMs = z
+    .number()
+    .int()
+    .positive()
+    .max(30 * DAY_MS);
+const gasAmount = positive;
+/** Absolute end of the agent's term, written on chain. The chain requires it within 30 days. */
+const expiresMs = z.number().int().positive();
+const name = z.string().regex(/^[\x20-\x7e]{1,64}$/);
+/**
+ * What the owner reviews and signs: one pass per agent, the owner's coins left in their own
+ * address balance under one allowance per coin the rules spend, the policies, and the gas terms.
+ */
+export const SetupSchema = z
+    .object({
+    name,
+    policy: PolicySchema,
+    ttlMs,
+    expiresMs,
+    /** Lifetime caps, by coin type: the hard backstop under the policies. */
+    allowances: z.record(coinType, positive),
+    gasAmount,
+    /** A separate SUI allowance for gas top-ups: lifetime cap and daily window. */
+    gasCap: positive,
+    gasDaily: positive,
+})
+    .strict()
+    .refine((s) => BigInt(s.gasDaily) <= BigInt(s.gasCap), 'Daily gas limit must not exceed the gas lifetime cap')
+    .refine((s) => {
+    const caps = new Set(Object.keys(s.allowances).map((c) => normalizeStructTag(c)));
+    const spent = spentCoins(s.policy);
+    return spent.every((c) => caps.has(c)) && caps.size === spent.length;
+}, 'Exactly the coins the rules spend need an allowance')
+    .refine(({ policy: p, allowances }) => {
+    const cap = (coin) => BigInt(allowances[normalizeStructTag(coin)] ?? '0');
+    return (p.transfers.every((t) => BigInt(t.daily) <= cap(t.coin)) &&
+        p.swaps.every((s) => BigInt(s.daily) <= cap(s.coinIn)) &&
+        p.lending.every((l) => BigInt(l.daily) <= cap(l.coin)) &&
+        (!p.staking || BigInt(p.staking.daily) <= cap(SUI)));
+}, 'A daily limit must not exceed the lifetime cap of its coin');
+/** What activation confirmed on chain: the pass, the owner's receipt for it, and the allowances. */
+export const ActiveSessionSchema = z
+    .object({
+    passId: address,
+    /** The discovery receipt in the owner's wallet. */
+    receiptId: address,
+    /** The pass-bound allowance and its revoke cap, by coin type. */
+    allowances: z.record(coinType, z.object({ allowance: address, revokeCap: address }).strict()),
+    /** The dedicated SUI gas allowance and its revoke cap. */
+    gasAllowance: address,
+    gasRevokeCap: address,
+    owner: address,
+    authorizationDigest: z.string().min(1),
+})
+    .strict();
+/** Decimal strings enter and leave the UI; all arithmetic stays in integer base units. */
+export function units(value, decimals) {
+    if (!new RegExp(`^(0|[1-9][0-9]*)(\\.[0-9]{1,${decimals}})?$`).test(value))
+        throw new Error(`Enter a non-negative number with at most ${decimals} decimals`);
+    const [whole, fraction = ''] = value.split('.');
+    return amount.parse((BigInt(whole) * 10n ** BigInt(decimals) + BigInt(fraction.padEnd(decimals, '0'))).toString());
+}
+export function display(value, decimals) {
+    const n = BigInt(value), scale = 10n ** BigInt(decimals);
+    const fraction = (n % scale).toString().padStart(decimals, '0').replace(/0+$/, '');
+    return `${n / scale}${fraction ? `.${fraction}` : ''}`;
+}
+/** A coin type as an owner can recognise it: the package's first and last characters and the name. */
+export function shortType(type) {
+    const [pkg, , name] = normalizeStructTag(type).split('::');
+    return `${pkg.slice(0, 6)}…${pkg.slice(-4)}::${name}`;
+}
+/** A coin's name as the page prints it: the symbol, plus the type when the deployment never vetted it. */
+export function coinLabel(d, type) {
+    const c = d.coins.find((x) => sameCoin(x.type, type));
+    if (!c)
+        return shortType(type);
+    return c.unlisted ? `${c.symbol} (${shortType(type)})` : c.symbol;
+}
+/** An amount of a coin in human terms, with its name. */
+export function showCoin(d, type, value) {
+    const c = d.coins.find((x) => sameCoin(x.type, type));
+    return c
+        ? `${display(value, c.decimals)} ${coinLabel(d, type)}`
+        : `${value} base units of ${type}`;
+}
+/** The coins and pools a policy names, for the facts a page or server must know about them. */
+export function policyNeeds(p) {
+    const coins = new Set(), pools = new Set();
+    for (const t of p.transfers)
+        coins.add(normalizeStructTag(t.coin));
+    for (const s of p.swaps) {
+        coins.add(normalizeStructTag(s.coinIn));
+        coins.add(normalizeStructTag(s.coinOut));
+        for (const id of s.pools)
+            pools.add(id);
+    }
+    for (const l of p.lending)
+        coins.add(normalizeStructTag(l.coin));
+    if (p.staking)
+        coins.add(SUI);
+    return { coins: [...coins], pools: [...pools] };
+}
+/**
+ * A swap policy's price scale is `coinOut` base units per 1e9 base units of `coinIn`. A human
+ * price is `coinOut` per one `coinIn`; the two differ by the coins' decimals.
+ */
+export function priceUnits(d, coinIn, coinOut, price) {
+    const shift = coinInfo(d, coinOut).decimals + 9 - coinInfo(d, coinIn).decimals;
+    if (shift >= 0)
+        return units(price, shift);
+    return (BigInt(units(price, 0)) / 10n ** BigInt(-shift)).toString();
+}
+export function priceDisplay(d, coinIn, coinOut, minPrice) {
+    const shift = coinInfo(d, coinOut).decimals + 9 - coinInfo(d, coinIn).decimals;
+    return shift >= 0
+        ? display(minPrice, shift)
+        : (BigInt(minPrice) * 10n ** BigInt(-shift)).toString();
+}
+/** 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
+ * agent burns the gas budget over days, not hours. */
+export const defaultGasDaily = (gasCap) => {
+    const fifth = BigInt(gasCap) / 5n;
+    return (fifth > 0n ? fifth : BigInt(gasCap)).toString();
+};
+/**
+ * What the rules can draw from the owner's address balance, by coin: each allowance's cap, and
+ * the gas cap on top for SUI. Keys are normalized coin types.
+ */
+export function drawable(setup) {
+    const need = {};
+    for (const [coin, cap] of Object.entries(setup.allowances))
+        need[normalizeStructTag(coin)] = (need[normalizeStructTag(coin)] ?? 0n) + BigInt(cap);
+    need[SUI] = (need[SUI] ?? 0n) + BigInt(setup.gasCap);
+    return Object.fromEntries(Object.entries(need).map(([c, v]) => [c, v.toString()]));
+}
+/**
+ * Allowances draw only from the owner's address balance, never from coin objects. What the
+ * authorization converts from the owner's coins into their address balance is, per coin, the
+ * shortfall between what the rules can draw (`drawable`) and what that balance already holds.
+ * Converted coins stay the owner's to spend.
+ */
+export function conversion(setup, held) {
+    const have = (coin) => BigInt(held[normalizeStructTag(coin)] ?? '0');
+    return Object.fromEntries(Object.entries(drawable(setup)).map(([coin, want]) => [
+        coin,
+        (BigInt(want) > have(coin) ? BigInt(want) - have(coin) : 0n).toString(),
+    ]));
+}
+/**
+ * SUI the owner must hold in total to sign, address balance and coin objects together: what the
+ * rules may draw, the stipend and a fee reserve. Gas comes from either side, so nothing has to
+ * be a coin object; the authorization consolidates what it touches into the address balance.
+ */
+export function requiredSui(setup) {
+    return (BigInt(drawable(setup)[SUI]) + BigInt(setup.gasAmount) + OWNER_FEE_RESERVE).toString();
+}
+/** Set aside for the owner's own transaction fees when checking what they hold. */
+export const OWNER_FEE_RESERVE = 50000000n;

package/dist/explorer.js

@@ -0,0 +1,143 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+import { normalizeSuiAddress } from '@mysten/sui/utils';
+import { createdEventType, discoverAllowances, parseCreated, readControl, } from './chain.js';
+import { describeAttempt } from './describe.js';
+async function createdEvents(client, d, limit, before = null) {
+    // Newest first; a continuation reads the page before the last cursor.
+    const page = await client.listEvents({
+        filter: { eventType: createdEventType(d) },
+        order: 'descending',
+        limit,
+        ...(before ? { before } : {}),
+    });
+    const summaries = await Promise.all(page.events.map(async (e) => {
+        const r = await client.getTransaction({ digest: e.transactionDigest }).catch(() => null);
+        const tx = r?.Transaction ?? r?.FailedTransaction;
+        return {
+            ...parseCreated(e.bcs),
+            digest: e.transactionDigest,
+            timestampMs: tx?.timestampMs ?? null,
+        };
+    }));
+    return { summaries, hasNextPage: page.hasNextPage, endCursor: page.endCursor };
+}
+/**
+ * The pass most recently created for an agent key, among the newest `Created` events: how the
+ * process that proposed a pass learns that the owner signed, with nothing sent back to it.
+ */
+export async function findPassByAgent(client, d, agent) {
+    const wanted = normalizeSuiAddress(agent);
+    let cursor = null;
+    for (let pages = 0; pages < 10; pages++) {
+        const page = await client.listEvents({
+            filter: { eventType: createdEventType(d) },
+            order: 'descending',
+            limit: 50,
+            ...(cursor ? { before: cursor } : {}),
+        });
+        for (const e of page.events) {
+            const created = parseCreated(e.bcs);
+            if (created.agent === wanted)
+                return { ...created, digest: e.transactionDigest };
+        }
+        if (!page.hasNextPage || !page.endCursor)
+            return null;
+        cursor = page.endCursor;
+    }
+    return null;
+}
+/**
+ * Every pass ever created for an agent key, newest first, among the package's `Created`
+ * events. A key is meant to sign one authorization; more than one here means a proposal was
+ * signed again.
+ */
+export async function passesByAgent(client, d, agent) {
+    const wanted = normalizeSuiAddress(agent), found = [];
+    let cursor = null;
+    for (let pages = 0; pages < 10; pages++) {
+        const page = await client.listEvents({
+            filter: { eventType: createdEventType(d) },
+            order: 'descending',
+            limit: 50,
+            ...(cursor ? { before: cursor } : {}),
+        });
+        for (const e of page.events) {
+            const created = parseCreated(e.bcs);
+            if (created.agent === wanted)
+                found.push({ ...created, digest: e.transactionDigest });
+        }
+        if (!page.hasNextPage || !page.endCursor)
+            break;
+        cursor = page.endCursor;
+    }
+    return found;
+}
+/** The most recently created passes on this package. */
+export async function listPasses(client, d, limit = 50) {
+    return (await createdEvents(client, d, limit)).summaries;
+}
+/** One pass's creation record, found among the package's `Created` events. */
+export async function findPass(client, d, passId) {
+    const wanted = normalizeSuiAddress(passId);
+    let cursor = null;
+    // A bounded scan: the demo package will not hold thousands of passes.
+    for (let pages = 0; pages < 40; pages++) {
+        const { summaries, hasNextPage, endCursor } = await createdEvents(client, d, 50, cursor);
+        const hit = summaries.find((s) => s.id === wanted);
+        if (hit)
+            return hit;
+        if (!hasNextPage || !endCursor)
+            return null;
+        cursor = endCursor;
+    }
+    return null;
+}
+/**
+ * The allowances and caps the authorization created, identified the way activation does: the
+ * pass-bound ones carry the `PASS` app and the owner as funder, the gas allowance its fixed
+ * name. Null once the owner has revoked, because the allowances no longer exist.
+ */
+export async function discoverActive(client, d, pass) {
+    const control = await readControl(client, d, pass.id);
+    const { allowances, gas } = await discoverAllowances(client, d, {
+        owner: pass.owner,
+        agent: control.agent,
+    });
+    if (!gas || Object.keys(allowances).length === 0)
+        return null;
+    return {
+        passId: pass.id,
+        receiptId: pass.receiptId,
+        allowances,
+        gasAllowance: gas.allowance,
+        gasRevokeCap: gas.revokeCap,
+        owner: pass.owner,
+        authorizationDigest: pass.digest,
+    };
+}
+const include = { transaction: true, balanceChanges: true };
+/** The agent's most recent transactions, newest first, read straight from the chain. */
+export async function agentAttempts(client, d, agent, recipients, limit = 30) {
+    const page = await client.listTransactions({
+        filter: { sender: agent },
+        order: 'descending',
+        limit,
+        include,
+    });
+    return page.transactions.map((r) => describeAttempt(d, agent, recipients, (r.Transaction ?? r.FailedTransaction)));
+}
+/** Every recent call into the package's `pass` module, from any agent or owner. */
+export async function packageFeed(client, d, limit = 40) {
+    const page = await client.listTransactions({
+        filter: { function: `${d.publishedAt}::pass` },
+        order: 'descending',
+        limit,
+        include,
+    });
+    return page.transactions.map((r) => {
+        const tx = (r.Transaction ?? r.FailedTransaction);
+        const sender = normalizeSuiAddress(tx.transaction?.sender ?? '0x0');
+        return { ...describeAttempt(d, sender, [], tx), sender };
+    });
+}

package/dist/float.js

@@ -0,0 +1,80 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+import { Transaction } from '@mysten/sui/transactions';
+import { readControl } from './chain.js';
+import { SUI } from './domain.js';
+import { SessionStore } from './storage.js';
+/** The least budget the network accepts for a transaction, at the reference gas price. */
+const MIN_BUDGET = 3000000n;
+/** Below this there is nothing worth a transaction. */
+const DUST = MIN_BUDGET + 1000000n;
+/** A pass is over when its object is gone (closed) or its agent is revoked (stopped). */
+export async function passEnded(client, d, passId) {
+    return client.getObject({ objectId: passId }).then(() => readControl(client, d, passId).then((c) => c.revoked), () => true);
+}
+/** A pass is closed when its object is gone. */
+export async function passClosed(client, passId) {
+    return client.getObject({ objectId: passId }).then(() => false, () => true);
+}
+/**
+ * Sends the session key's whole SUI address balance to `owner`, less the gas this transaction
+ * itself costs: a first simulation prices it, the real transaction keeps twice that as budget
+ * and sends the rest, so what stays behind is about one transaction's fee. Returns the digest,
+ * or null when the float was dust.
+ */
+export async function returnGasFloat(client, directory, sessionAddress, owner) {
+    // Another process (the session's own signer, say) may be sweeping at the same moment; a
+    // rejection for a balance that moved under us is answered by looking again.
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await sweepOnce(client, directory, sessionAddress, owner);
+        }
+        catch (error) {
+            if (attempt > 0 || !/[Ii]nsufficient/.test(error.message))
+                throw error;
+            await new Promise((r) => setTimeout(r, 3000));
+        }
+    }
+}
+async function sweepOnce(client, directory, sessionAddress, owner) {
+    const { balance } = await client.getBalance({ owner: sessionAddress, coinType: SUI });
+    const float = BigInt(balance.addressBalance);
+    if (float <= DUST)
+        return null;
+    const build = (amount, budget) => {
+        const tx = new Transaction();
+        tx.setSender(sessionAddress);
+        tx.setGasPayment([]);
+        tx.setGasBudget(Number(budget));
+        tx.moveCall({
+            target: '0x2::balance::send_funds',
+            typeArguments: [SUI],
+            arguments: [tx.balance({ balance: amount.toString() }), tx.pure.address(owner)],
+        });
+        return tx;
+    };
+    const probeBudget = MIN_BUDGET;
+    const sim = await client.simulateTransaction({
+        transaction: build(float - probeBudget, probeBudget),
+        include: { effects: true },
+    });
+    const t = sim.$kind === 'Transaction' ? sim.Transaction : sim.FailedTransaction;
+    if (!t.status.success)
+        throw new Error(`Could not price the sweep: ${t.status.error?.message}`);
+    const used = t.effects.gasUsed;
+    const fee = BigInt(used?.computationCost ?? '0') +
+        BigInt(used?.storageCost ?? '0') -
+        BigInt(used?.storageRebate ?? '0');
+    const budget = fee * 2n > MIN_BUDGET ? fee * 2n : MIN_BUDGET;
+    if (float <= budget)
+        return null;
+    const amount = float - budget;
+    const result = await client.signAndExecuteTransaction({
+        transaction: build(amount, budget),
+        signer: await SessionStore.keyOf(directory),
+    });
+    if (result.$kind !== 'Transaction')
+        throw new Error(`The sweep was refused: ${result.FailedTransaction.status.error?.message}`);
+    await client.waitForTransaction({ result });
+    return { digest: result.Transaction.digest, amount: amount.toString() };
+}