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

package/dist/chain.js

@@ -0,0 +1,763 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+/** Only this module translates Move storage into application read models. */
+import { bcs } from '@mysten/sui/bcs';
+import { ObjectError } from '@mysten/sui/client';
+import { GrpcWebFetchTransport, RpcError, SuiGrpcClient } from '@mysten/sui/grpc';
+import { Transaction } from '@mysten/sui/transactions';
+import { normalizeStructTag, normalizeSuiAddress, parseStructTag } from '@mysten/sui/utils';
+import { UnaryCall } from '@protobuf-ts/runtime-rpc';
+import { AGENT_GAS_NAME, DAY_MS, sameCoin, SUI, } from './domain.js';
+// === BCS layouts of the Move types this module reads ===
+const idBcs = bcs.Address;
+const bagBcs = bcs.struct('Bag', { id: idBcs, size: bcs.u64() });
+const controlBcs = bcs.struct('Control', {
+    controller: idBcs,
+    name: bcs.string(),
+    owner: bcs.Address,
+    agent: bcs.Address,
+    agent_expires_ms: bcs.u64(),
+    policies: bcs.struct('Policies', { bag: bagBcs }),
+    positions: bagBcs,
+});
+const passBcs = bcs.struct('Pass', { id: idBcs, control: controlBcs });
+const meterBcs = bcs.struct('Meter', { day: bcs.u64(), used: bcs.u64() });
+const transferPolicyBcs = bcs.struct('TransferPolicy', {
+    recipients: bagBcs,
+    per_transfer: bcs.u64(),
+    daily: bcs.u64(),
+    meter: meterBcs,
+});
+const swapPolicyBcs = bcs.struct('SwapPolicy', {
+    venues: bcs.vector(idBcs),
+    per_trade: bcs.u64(),
+    daily: bcs.u64(),
+    min_price: bcs.u64(),
+    meter: meterBcs,
+});
+const lendingPolicyBcs = bcs.struct('LendingPolicy', {
+    pool: idBcs,
+    asset: bcs.u8(),
+    allow_borrow: bcs.bool(),
+    per_action: bcs.u64(),
+    daily: bcs.u64(),
+    min_health_factor: bcs.u256(),
+    meter: meterBcs,
+});
+const stakingPolicyBcs = bcs.struct('StakingPolicy', {
+    validators: bcs.vector(bcs.Address),
+    per_stake: bcs.u64(),
+    daily: bcs.u64(),
+    meter: meterBcs,
+});
+const accountCapBcs = bcs.struct('AccountCap', {
+    id: idBcs,
+    owner: bcs.Address,
+});
+/** The position address a NAVI account cap controls, from the cap object's content. */
+export const naviAccountOwner = (content) => normalizeSuiAddress(accountCapBcs.parse(content).owner);
+const stakedSuiBcs = bcs.struct('StakedSui', {
+    id: idBcs,
+    pool_id: idBcs,
+    stake_activation_epoch: bcs.u64(),
+    principal: bcs.u64(),
+});
+const STAKED_SUI_TYPE = normalizeStructTag('0x3::staking_pool::StakedSui');
+const rateLimitBcs = bcs.enum('RateLimit', {
+    Windowed: bcs.struct('Windowed', {
+        limit: bcs.u256(),
+        spent: bcs.u256(),
+        anchor_ms: bcs.option(bcs.u64()),
+        index: bcs.u64(),
+        window: bcs.enum('Window', {
+            PeriodicMs: bcs.u64(),
+            CalendarMonths: bcs.u8(),
+        }),
+    }),
+});
+const allowanceBcs = bcs.struct('Allowance', {
+    id: idBcs,
+    settings: bcs.struct('Settings', {
+        funder: bcs.Address,
+        spender: bcs.option(bcs.Address),
+        app: bcs.option(bcs.struct('TypeName', { name: bcs.string() })),
+        lifetime_cap: bcs.option(bcs.u256()),
+        start_timestamp_ms: bcs.option(bcs.u64()),
+        expiration_timestamp_ms: bcs.option(bcs.u64()),
+        rate_limit: bcs.option(rateLimitBcs),
+        name: bcs.string(),
+    }),
+    current_spend: bcs.u256(),
+});
+const allowanceCapBcs = bcs.struct('AllowanceCap', { id: idBcs, allowance: idBcs });
+const clockBcs = bcs.struct('Clock', { id: idBcs, timestamp_ms: bcs.u64() });
+const createdBcs = bcs.struct('Created', {
+    pass: idBcs,
+    receipt: idBcs,
+    name: bcs.string(),
+    owner: bcs.Address,
+    agent: bcs.Address,
+    agent_expires_ms: bcs.u64(),
+});
+const issuedBcs = bcs.struct('Issued', {
+    pass: idBcs,
+    coin_type: bcs.struct('TypeName', { name: bcs.string() }),
+    lifetime_cap: bcs.option(bcs.u256()),
+    expires_ms: bcs.option(bcs.u64()),
+});
+const receiptBcs = bcs.struct('Receipt', {
+    id: idBcs,
+    pass: idBcs,
+    name: bcs.string(),
+});
+/** The app type that binds allowances to the `pass` module. */
+export const appType = (d) => `${d.packageId}::pass::PASS`;
+export const createdEventType = (d) => `${d.packageId}::pass::Created`;
+export function parseCreated(bytes) {
+    const c = createdBcs.parse(bytes);
+    return {
+        id: normalizeSuiAddress(c.pass),
+        receiptId: normalizeSuiAddress(c.receipt),
+        name: c.name,
+        owner: normalizeSuiAddress(c.owner),
+        agent: normalizeSuiAddress(c.agent),
+        agentExpiresMs: c.agent_expires_ms,
+    };
+}
+/** The pass receipts in a wallet, for discovery without any local state. */
+export async function listReceipts(client, d, owner) {
+    const receipts = [];
+    let cursor = null;
+    do {
+        const page = await client.listOwnedObjects({
+            owner,
+            type: receiptType(d),
+            cursor,
+            include: { content: true },
+        });
+        for (const o of page.objects) {
+            const r = receiptBcs.parse(o.content);
+            receipts.push({
+                id: normalizeSuiAddress(r.id),
+                pass: normalizeSuiAddress(r.pass),
+                name: r.name,
+            });
+        }
+        cursor = page.hasNextPage ? page.cursor : null;
+    } while (cursor);
+    return receipts;
+}
+/** The owner's discovery receipt for a pass. */
+export const receiptType = (d) => `${d.packageId}::pass::Receipt`;
+export const allowanceType = (coin) => `0x2::allowance::Allowance<0x2::balance::Balance<${coin}>>`;
+export const allowanceCapType = (coin) => `0x2::allowance::AllowanceCap<0x2::balance::Balance<${coin}>>`;
+export const policyType = (d, module, name, typeArguments) => normalizeStructTag(`${d.packageId}::${module}::${name}${typeArguments.length ? `<${typeArguments.join(',')}>` : ''}`);
+const typeNameTag = (name) => normalizeStructTag(`0x${name}`);
+export async function readAuthorization(client, d, digest) {
+    const result = await client.waitForTransaction({
+        digest,
+        include: {
+            events: true,
+            transaction: true,
+            effects: true,
+            objectTypes: true,
+            balanceChanges: true,
+        },
+    });
+    if (result.$kind !== 'Transaction')
+        throw new Error('Authorization transaction failed on chain');
+    const tx = result.Transaction;
+    if (!tx.transaction?.sender)
+        throw new Error('Authorization has no sender');
+    const events = (type) => tx.events.filter((e) => e.eventType === type);
+    return {
+        sender: normalizeSuiAddress(tx.transaction.sender),
+        passes: events(createdEventType(d)).map((e) => parseCreated(e.bcs)),
+        issued: events(`${d.packageId}::pass::Issued`).map((e) => {
+            const i = issuedBcs.parse(e.bcs);
+            return {
+                passId: normalizeSuiAddress(i.pass),
+                coinType: typeNameTag(i.coin_type.name),
+                lifetimeCap: i.lifetime_cap,
+                expiresMs: i.expires_ms,
+            };
+        }),
+        balanceChanges: (tx.balanceChanges ?? []).map((c) => ({
+            address: normalizeSuiAddress(c.address),
+            coinType: normalizeStructTag(c.coinType),
+            amount: c.amount,
+        })),
+        objects: tx
+            // Dynamic-field children (policy bag entries) carry no type here and are not needed.
+            .effects.changedObjects.filter((o) => o.idOperation === 'Created' && tx.objectTypes[o.objectId])
+            .map((o) => ({
+            id: normalizeSuiAddress(o.objectId),
+            type: normalizeStructTag(tx.objectTypes[o.objectId]),
+            owner: o.outputOwner?.$kind === 'AddressOwner'
+                ? normalizeSuiAddress(o.outputOwner.AddressOwner)
+                : null,
+            shared: o.outputOwner?.$kind === 'Shared',
+        })),
+    };
+}
+/** Public fullnodes rate-limit by IP; a 429 is retried with these pauses before it surfaces. */
+const RETRY_PAUSES_MS = [500, 1000, 2000, 4000];
+const rateLimited = (e) => e instanceof RpcError && e.code === 'RESOURCE_EXHAUSTED';
+class RetryingTransport extends GrpcWebFetchTransport {
+    unary(method, input, options) {
+        const settled = (async () => {
+            for (let attempt = 0;; attempt++) {
+                const call = super.unary(method, input, options);
+                try {
+                    await call.response;
+                    return call;
+                }
+                catch (e) {
+                    if (!rateLimited(e) || attempt >= RETRY_PAUSES_MS.length)
+                        throw e;
+                    for (const p of [call.headers, call.status, call.trailers])
+                        p.catch(() => { });
+                    await new Promise((r) => setTimeout(r, RETRY_PAUSES_MS[attempt]));
+                }
+            }
+        })();
+        return new UnaryCall(method, options.meta ?? {}, input, settled.then((c) => c.headers), settled.then((c) => c.response), settled.then((c) => c.status), settled.then((c) => c.trailers));
+    }
+}
+export function clientFor(d) {
+    return new SuiGrpcClient({
+        network: d.network,
+        transport: new RetryingTransport({ baseUrl: d.grpcUrl }),
+    });
+}
+export async function assertChain(client, d) {
+    let actual;
+    try {
+        actual = (await client.getChainIdentifier()).chainIdentifier;
+    }
+    catch (error) {
+        throw new Error(`Could not reach ${d.network} at ${d.grpcUrl}: ${error.message}. Check the network connection and try again.`);
+    }
+    if (actual !== d.chainIdentifier)
+        throw new Error(`${d.grpcUrl} is not the ${d.network} chain this deployment was made for`);
+}
+async function chainTime(client) {
+    const { object } = await client.getObject({
+        objectId: '0x6',
+        include: { content: true },
+    });
+    return Number(clockBcs.parse(object.content).timestamp_ms);
+}
+/** A meter as the chain would apply it now: the stored count, or zero after midnight. */
+function usage(m, now) {
+    const day = Math.floor(now / DAY_MS);
+    return {
+        usedToday: day > Number(m.day) ? '0' : m.used,
+        resetsAtMs: (day + 1) * DAY_MS,
+    };
+}
+async function dynamicFields(client, parentId) {
+    const fields = [];
+    let cursor = null;
+    do {
+        const page = await client.listDynamicFields({
+            parentId,
+            cursor,
+            include: { value: true },
+        });
+        fields.push(...page.dynamicFields);
+        cursor = page.hasNextPage ? page.cursor : null;
+    } while (cursor);
+    return fields;
+}
+/** Policies are dynamic fields of the control's bag, one per policy type. */
+async function readPolicies(client, d, bagId, now) {
+    const policies = { transfers: [], swaps: [], lending: [], staking: [] };
+    for (const field of await dynamicFields(client, bagId)) {
+        const tag = parseStructTag(field.valueType);
+        if (normalizeSuiAddress(tag.address) !== d.packageId)
+            continue;
+        const args = tag.typeParams.map((t) => normalizeStructTag(typeof t === 'string' ? t : t));
+        if (tag.module === 'transfer_policy') {
+            const p = transferPolicyBcs.parse(field.value.bcs);
+            const recipients = (await dynamicFields(client, normalizeSuiAddress(p.recipients.id))).map((r) => ({
+                name: bcs.string().parse(r.name.bcs),
+                address: normalizeSuiAddress(bcs.Address.parse(r.value.bcs)),
+            }));
+            recipients.sort((a, b) => a.name.localeCompare(b.name));
+            policies.transfers.push({
+                coinType: args[0],
+                recipients,
+                perTransfer: p.per_transfer,
+                daily: p.daily,
+                usage: usage(p.meter, now),
+            });
+        }
+        else if (tag.module === 'swap_policy') {
+            const p = swapPolicyBcs.parse(field.value.bcs);
+            policies.swaps.push({
+                coinIn: args[0],
+                coinOut: args[1],
+                venues: p.venues.map((v) => normalizeSuiAddress(v)),
+                perTrade: p.per_trade,
+                daily: p.daily,
+                minPrice: p.min_price,
+                usage: usage(p.meter, now),
+            });
+        }
+        else if (tag.module === 'lending_policy') {
+            const p = lendingPolicyBcs.parse(field.value.bcs);
+            policies.lending.push({
+                coinType: args[0],
+                poolId: normalizeSuiAddress(p.pool),
+                asset: p.asset,
+                allowBorrow: p.allow_borrow,
+                perAction: p.per_action,
+                daily: p.daily,
+                minHealthFactor: p.min_health_factor,
+                usage: usage(p.meter, now),
+            });
+        }
+        else if (tag.module === 'staking_policy') {
+            const p = stakingPolicyBcs.parse(field.value.bcs);
+            policies.staking.push({
+                validators: p.validators.map((v) => normalizeSuiAddress(v)),
+                perStake: p.per_stake,
+                daily: p.daily,
+                usage: usage(p.meter, now),
+            });
+        }
+    }
+    const byType = (a, b) => a.coinType.localeCompare(b.coinType);
+    policies.transfers.sort(byType);
+    policies.lending.sort(byType);
+    policies.swaps.sort((a, b) => (a.coinIn + a.coinOut).localeCompare(b.coinIn + b.coinOut));
+    return policies;
+}
+export async function readControl(client, d, id) {
+    const [{ object }, now] = await Promise.all([
+        client.getObject({ objectId: id, include: { content: true } }),
+        chainTime(client),
+    ]);
+    if (normalizeStructTag(object.type) !== normalizeStructTag(`${d.packageId}::pass::AgentPass`) ||
+        object.owner.$kind !== 'Shared')
+        throw new Error('Unexpected pass type or ownership');
+    const { control } = passBcs.parse(object.content);
+    const [policies, positions] = await Promise.all([
+        readPolicies(client, d, normalizeSuiAddress(control.policies.bag.id), now),
+        dynamicFields(client, normalizeSuiAddress(control.positions.id)),
+    ]);
+    const navi = positions.find((p) => normalizeStructTag(p.valueType) ===
+        normalizeStructTag(`${d.protocols.navi.packageId}::account::AccountCap`));
+    const stakes = positions
+        .filter((p) => normalizeStructTag(p.valueType) === STAKED_SUI_TYPE)
+        .map((p) => {
+        const s = stakedSuiBcs.parse(p.value.bcs);
+        return {
+            id: normalizeSuiAddress(s.id),
+            poolId: normalizeSuiAddress(s.pool_id),
+            activationEpoch: s.stake_activation_epoch,
+            principal: s.principal,
+        };
+    })
+        .sort((a, b) => a.id.localeCompare(b.id));
+    return {
+        id: normalizeSuiAddress(control.controller),
+        name: control.name,
+        owner: normalizeSuiAddress(control.owner),
+        agent: normalizeSuiAddress(control.agent),
+        agentExpiresMs: control.agent_expires_ms,
+        revoked: control.agent_expires_ms === '0',
+        policies,
+        naviPosition: navi ? normalizeSuiAddress(accountCapBcs.parse(navi.value.bcs).owner) : null,
+        stakes,
+        chainTimeMs: now,
+    };
+}
+/** Address balances of any address. */
+/**
+ * A DeepBook pool's mid price, in quote base units per 1e9 base units of base: the scale of a
+ * swap policy's floor for selling the base. Read by simulating `pool::mid_price` on the latest
+ * package, since the original is version-gated.
+ */
+export async function midPrice(client, d, pool) {
+    const tx = new Transaction();
+    tx.setSender(normalizeSuiAddress('0x1'));
+    tx.moveCall({
+        target: `${d.protocols.deepbook.publishedAt}::pool::mid_price`,
+        typeArguments: [pool.coinA, pool.coinB],
+        arguments: [tx.object(pool.poolId), tx.object('0x6')],
+    });
+    const result = await client.simulateTransaction({
+        transaction: tx,
+        include: { commandResults: true },
+    });
+    const value = result.commandResults?.[0]?.returnValues?.[0]?.bcs;
+    const executed = result.$kind === 'Transaction' ? result.Transaction : result.FailedTransaction;
+    if (!executed?.status.success || !value)
+        throw new Error(executed?.status.error?.message ?? 'No price returned');
+    return bcs.u64().parse(value);
+}
+/**
+ * A DeepBook pool's order sizes, in base-coin base units: an order under `minSize` fills
+ * nothing, and sizes are rounded down to `lotSize`. Read by simulation on the latest package.
+ */
+export async function deepbookSizes(client, d, pool) {
+    const tx = new Transaction();
+    tx.setSender(normalizeSuiAddress('0x1'));
+    tx.moveCall({
+        target: `${d.protocols.deepbook.publishedAt}::pool::pool_book_params`,
+        typeArguments: [pool.coinA, pool.coinB],
+        arguments: [tx.object(pool.poolId)],
+    });
+    const result = await client.simulateTransaction({
+        transaction: tx,
+        include: { commandResults: true },
+    });
+    const values = result.commandResults?.[0]?.returnValues;
+    const executed = result.$kind === 'Transaction' ? result.Transaction : result.FailedTransaction;
+    if (!executed?.status.success || !values || values.length < 3)
+        throw new Error(executed?.status.error?.message ?? 'No pool parameters returned');
+    return { lotSize: bcs.u64().parse(values[1].bcs), minSize: bcs.u64().parse(values[2].bcs) };
+}
+/**
+ * What a listed pool would give for `amountIn` of `coinIn` right now, read from the venue's own
+ * quote function by simulation, so it touches no allowance. `amountIn` is what the pool would
+ * actually take: DeepBook pays the taker fee out of the input and rounds the rest down to the
+ * lot size, so a small order can fill nothing; Cetus may stop short when liquidity runs out.
+ */
+export async function quoteSwap(client, d, pool, coinIn, amountIn) {
+    const forward = sameCoin(pool.coinA, coinIn);
+    const tx = new Transaction();
+    tx.setSender(normalizeSuiAddress('0x1'));
+    if (pool.venue === 'deepbook')
+        tx.moveCall({
+            target: `${d.protocols.deepbook.publishedAt}::pool::${forward ? 'get_quote_quantity_out_input_fee' : 'get_base_quantity_out_input_fee'}`,
+            typeArguments: [pool.coinA, pool.coinB],
+            arguments: [tx.object(pool.poolId), tx.pure.u64(amountIn), tx.object('0x6')],
+        });
+    else
+        tx.moveCall({
+            target: `${d.protocols.cetus.publishedAt}::pool::calculate_swap_result`,
+            typeArguments: [pool.coinA, pool.coinB],
+            arguments: [
+                tx.object(pool.poolId),
+                tx.pure.bool(forward),
+                tx.pure.bool(true),
+                tx.pure.u64(amountIn),
+            ],
+        });
+    const result = await client.simulateTransaction({
+        transaction: tx,
+        include: { commandResults: true },
+    });
+    const executed = result.$kind === 'Transaction' ? result.Transaction : result.FailedTransaction;
+    const values = result.commandResults?.[0]?.returnValues;
+    if (!executed?.status.success || !values?.[0]?.bcs)
+        throw new Error(executed?.status.error?.message ?? 'No quote returned');
+    if (pool.venue === 'deepbook') {
+        // (base out, quote out, DEEP required): the input side's value is what stayed unfilled.
+        const [base, quote] = [values[0].bcs, values[1].bcs].map((v) => bcs.u64().parse(v));
+        const unfilled = forward ? base : quote;
+        return {
+            amountIn: (BigInt(amountIn) - BigInt(unfilled)).toString(),
+            amountOut: forward ? quote : base,
+        };
+    }
+    const quote = bcs
+        .struct('CalculatedSwapResult', { amountIn: bcs.u64(), amountOut: bcs.u64() })
+        .parse(values[0].bcs);
+    return { amountIn: quote.amountIn, amountOut: quote.amountOut };
+}
+/** The owner's address balance of every listed coin, by normalized coin type. */
+export async function readBalances(client, d, owner) {
+    const held = await readHoldings(client, d, owner);
+    return Object.fromEntries(Object.entries(held).map(([c, h]) => [c, h.addressBalance]));
+}
+/**
+ * Every listed coin an address holds, split the way the chain splits it: the address balance,
+ * which allowances draw from and gas may come from, and coin objects, which only the owner's
+ * own transactions can move.
+ */
+export async function readHoldings(client, d, owner) {
+    const entries = await Promise.all(d.coins.map(async (c) => {
+        const { balance } = await client.getBalance({ owner, coinType: c.type });
+        return [
+            normalizeStructTag(c.type),
+            { addressBalance: balance.addressBalance, coinBalance: balance.coinBalance },
+        ];
+    }));
+    return Object.fromEntries(entries);
+}
+/** The coin a `0x2::allowance::Allowance<Balance<T>>` type names. */
+export function allowanceCoin(type) {
+    const tag = parseStructTag(type);
+    if (normalizeSuiAddress(tag.address) !== normalizeSuiAddress('0x2') ||
+        tag.module !== 'allowance' ||
+        tag.name !== 'Allowance')
+        return null;
+    const inner = tag.typeParams[0];
+    if (!inner || typeof inner === 'string')
+        return null;
+    const coin = inner.typeParams[0];
+    return coin ? normalizeStructTag(typeof coin === 'string' ? coin : coin) : null;
+}
+/** Returns null once the owner has revoked: `sui::allowance::revoke` deletes the object. */
+export async function readAllowance(client, id, coinType) {
+    let object;
+    try {
+        ({ object } = await client.getObject({
+            objectId: id,
+            include: { content: true },
+        }));
+    }
+    catch (error) {
+        if (error instanceof ObjectError && (error.reason === 'deleted' || error.reason === 'notFound'))
+            return null;
+        throw error;
+    }
+    if (normalizeStructTag(object.type) !== normalizeStructTag(allowanceType(coinType)) ||
+        object.owner.$kind !== 'Shared')
+        throw new Error('Unexpected allowance type or ownership');
+    const now = await chainTime(client);
+    const a = allowanceBcs.parse(object.content), s = a.settings, r = s.rate_limit?.Windowed;
+    let rateLimit = null;
+    if (r) {
+        const periodMs = r.window.PeriodicMs ?? null;
+        let spentNow = r.spent;
+        if (r.anchor_ms !== null && periodMs !== null) {
+            const current = Math.floor((now - Number(r.anchor_ms)) / Number(periodMs));
+            if (current > Number(r.index))
+                spentNow = '0';
+        }
+        rateLimit = {
+            limit: r.limit,
+            spent: r.spent,
+            spentNow,
+            anchorMs: r.anchor_ms,
+            index: r.index,
+            periodMs,
+            months: r.window.CalendarMonths ?? null,
+        };
+    }
+    return {
+        id: normalizeSuiAddress(a.id),
+        coinType,
+        funder: normalizeSuiAddress(s.funder),
+        spender: s.spender ? normalizeSuiAddress(s.spender) : null,
+        app: s.app ? typeNameTag(s.app.name) : null,
+        name: s.name,
+        lifetimeCap: s.lifetime_cap,
+        startMs: s.start_timestamp_ms,
+        expirationMs: s.expiration_timestamp_ms,
+        rateLimit,
+        currentSpend: a.current_spend,
+        chainTimeMs: now,
+    };
+}
+/** The allowance an `AllowanceCap` revokes, so a cap can be paired with its allowance. */
+export async function readAllowanceCapTarget(client, id) {
+    const { object } = await client.getObject({ objectId: id, include: { content: true } });
+    return normalizeSuiAddress(allowanceCapBcs.parse(object.content).allowance);
+}
+/**
+ * Every allowance currently bound to a pass, found from the owner's wallet: each `AllowanceCap`
+ * there names an allowance, and an allowance belongs to this pass when the pass's app type,
+ * owner and agent key are its app, funder and spender. The gas allowance is the plain one for
+ * the same agent. Reads the chain as it is now, so a changed pass reads right too.
+ */
+export async function discoverAllowances(client, d, pass) {
+    const app = normalizeStructTag(appType(d)), owner = normalizeSuiAddress(pass.owner), agent = normalizeSuiAddress(pass.agent);
+    const caps = [];
+    let cursor = null;
+    do {
+        const page = await client.listOwnedObjects({
+            owner,
+            cursor,
+            limit: 50,
+        });
+        for (const o of page.objects) {
+            const tag = parseStructTag(o.type);
+            if (normalizeSuiAddress(tag.address) === normalizeSuiAddress('0x2') &&
+                tag.module === 'allowance' &&
+                tag.name === 'AllowanceCap')
+                caps.push(o.objectId);
+        }
+        cursor = page.hasNextPage ? page.cursor : null;
+    } while (cursor && caps.length < 1000);
+    const allowances = {};
+    let gas = null;
+    await Promise.all(caps.map(async (cap) => {
+        const target = await readAllowanceCapTarget(client, cap).catch(() => null);
+        if (!target)
+            return;
+        const { object } = await client
+            .getObject({ objectId: target })
+            .catch(() => ({ object: null }));
+        const coin = object ? allowanceCoin(object.type) : null;
+        if (!coin)
+            return;
+        const view = await readAllowance(client, target, coin);
+        if (!view || view.funder !== owner || view.spender !== agent)
+            return;
+        if (view.app === app)
+            allowances[coin] = { allowance: target, revokeCap: cap };
+        else if (view.app === null && view.name === AGENT_GAS_NAME && coin === SUI)
+            gas = { allowance: target, revokeCap: cap };
+    }));
+    return { allowances, gas };
+}
+/** The pass-bound allowances of an active session, by coin; null where one no longer exists. */
+export async function readAllowances(client, active) {
+    const entries = await Promise.all(Object.entries(active.allowances).map(async ([coin, ids]) => [
+        coin,
+        await readAllowance(client, ids.allowance, coin),
+    ]));
+    return Object.fromEntries(entries);
+}
+/**
+ * The deployment extended with every coin and pool `needs` names that it does not list, read
+ * from the chain rather than taken from whoever wrote the proposal: a coin's symbol and
+ * decimals from its `CoinMetadata`, a pool's venue and coin order from its object type, which
+ * must be a `Pool` of one of the deployment's venue packages. Coins added this way carry
+ * `unlisted`, so pages print their type beside the symbol. Lending stays with the reserves the
+ * deployment lists.
+ */
+export async function withMarketFacts(client, d, needs) {
+    const coins = [...d.coins], pools = [...d.pools];
+    const venues = [
+        ['deepbook', d.protocols.deepbook.packageId],
+        ['cetus', d.protocols.cetus.packageId],
+    ];
+    for (const id of needs.pools) {
+        if (pools.some((p) => normalizeSuiAddress(p.poolId) === normalizeSuiAddress(id)))
+            continue;
+        const { object } = await client.getObject({ objectId: id });
+        const tag = parseStructTag(object.type);
+        const venue = venues.find(([, pkg]) => normalizeSuiAddress(tag.address) === normalizeSuiAddress(pkg))?.[0];
+        const [coinA, coinB] = tag.typeParams;
+        if (!venue || tag.module !== 'pool' || tag.name !== 'Pool' || !coinA || !coinB)
+            throw new Error(`${id} is not a DeepBook or Cetus pool on this network`);
+        const show = (t) => typeof t === 'string' ? normalizeStructTag(t) : normalizeStructTag(structTagString(t));
+        pools.push({ venue, poolId: normalizeSuiAddress(id), coinA: show(coinA), coinB: show(coinB) });
+    }
+    const wanted = new Set(needs.coins.map((c) => normalizeStructTag(c)));
+    for (const p of pools) {
+        wanted.add(p.coinA);
+        wanted.add(p.coinB);
+    }
+    for (const type of wanted) {
+        if (coins.some((c) => sameCoin(c.type, type)))
+            continue;
+        const { coinMetadata } = await client.getCoinMetadata({ coinType: type });
+        if (!coinMetadata)
+            throw new Error(`${type} has no coin metadata on this network`);
+        coins.push({
+            type,
+            symbol: coinMetadata.symbol.slice(0, 16) || 'COIN',
+            decimals: coinMetadata.decimals,
+            unlisted: true,
+        });
+    }
+    return { ...d, coins, pools };
+}
+function structTagString(t) {
+    const params = t.typeParams.map((p) => (typeof p === 'string' ? p : structTagString(p)));
+    return `${t.address}::${t.module}::${t.name}${params.length ? `<${params.join(',')}>` : ''}`;
+}
+/**
+ * Every coin an address holds, listed or not, with the metadata the chain publishes for it:
+ * what an agent needs to notice a coin the deployment does not list yet and talk about it
+ * by name. Pages through the owner's balances; a wallet with hundreds of coin types is rare.
+ */
+export async function readAllHoldings(client, d, owner) {
+    const balances = [];
+    let cursor = null;
+    do {
+        const page = await client.listBalances({
+            owner,
+            cursor,
+            limit: 50,
+        });
+        balances.push(...page.balances);
+        cursor = page.hasNextPage ? page.cursor : null;
+    } while (cursor && balances.length < 500);
+    return Promise.all(balances.map(async (b) => {
+        const type = normalizeStructTag(b.coinType);
+        const listed = d.coins.find((c) => sameCoin(c.type, type));
+        const meta = listed
+            ? null
+            : await client
+                .getCoinMetadata({ coinType: type })
+                .then((r) => r.coinMetadata)
+                .catch(() => null);
+        return {
+            coinType: type,
+            symbol: listed?.symbol ?? meta?.symbol ?? null,
+            decimals: listed?.decimals ?? meta?.decimals ?? null,
+            addressBalance: b.addressBalance,
+            coinBalance: b.coinBalance,
+            listed: !!listed,
+        };
+    }));
+}
+/** Live chain state for an authorized session. Nothing here is cached or decided locally. */
+export async function readStatus(client, d, active, sessionAddress) {
+    const [control, allowances, ownerBalances, gas] = await Promise.all([
+        readControl(client, d, active.passId),
+        readAllowances(client, active),
+        readHoldings(client, d, active.owner),
+        client.getBalance({ owner: sessionAddress }).then((r) => r.balance),
+    ]);
+    return {
+        control,
+        allowances,
+        ownerBalances,
+        revoked: Object.values(allowances).some((a) => !a) || control.revoked,
+        gas,
+    };
+}
+/**
+ * Addresses of the active validators. The system state keeps them in its versioned inner
+ * object, a dynamic field of `0x5`, read here through its JSON rendering.
+ */
+export async function activeValidators(client) {
+    const { dynamicFields } = await client.listDynamicFields({ parentId: '0x5' });
+    for (const field of dynamicFields) {
+        const { object } = await client.getObject({
+            objectId: field.fieldId,
+            include: { json: true },
+        });
+        const found = findActiveValidators(object.json);
+        if (found.length)
+            return found;
+    }
+    return [];
+}
+function findActiveValidators(node) {
+    if (!node || typeof node !== 'object')
+        return [];
+    const o = node;
+    if (Array.isArray(o.active_validators))
+        return o.active_validators.flatMap((v) => {
+            const address = v?.metadata?.sui_address;
+            return typeof address === 'string' ? [normalizeSuiAddress(address)] : [];
+        });
+    for (const value of Object.values(o)) {
+        const found = findActiveValidators(value);
+        if (found.length)
+            return found;
+    }
+    return [];
+}
+export function explorer(d, digest) {
+    return d.network === 'localnet'
+        ? null
+        : `https://suiscan.xyz/${d.network}/tx/${encodeURIComponent(digest)}`;
+}
+export function explorerObject(d, id) {
+    return d.network === 'localnet' ? null : `https://suiscan.xyz/${d.network}/object/${id}`;
+}
+export function explorerAddress(d, address) {
+    return d.network === 'localnet' ? null : `https://suiscan.xyz/${d.network}/account/${address}`;
+}