@mysten-incubation/sui-agent-pass 0.1.12 → 0.1.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -9,11 +9,11 @@ and the chain identifier for that network. The stdio server loads one of these w
9
9
  the agent names a `network` in `propose_authorization`, so an installed client needs no local
10
10
  publish; a private `deployment.json` under `~/.sui-agent-pass` or a `deployment` path overrides.
11
11
 
12
- `mainnet.json` is the mainnet test copy of the package (`0x4736026b…0a22`, published
12
+ `mainnet.json` is the mainnet test copy of the package (`0x389b5817…063f`, published
13
13
  2026-10-28 from the code that will launch, caps with its publisher), for dogfooding with small
14
14
  sums; the real launch will be a fresh publish and a new file here. Its `siteUrl` sends owners to
15
15
  the hosted site. `testnet.json` is the same code, published to testnet on 2026-10-28
16
- (`0x52017f8e…17b6`) with its stand-in markets and the demo faucet. The shipped copy lists no pools and no reserves on purpose: the testnet markets are
16
+ (`0xb6e9d01e…1bf0`) with its stand-in markets and the demo faucet. The shipped copy lists no pools and no reserves on purpose: the testnet markets are
17
17
  stand-ins with 2 SUI of depth, so dogfooders get transfers and staking there and trade on
18
18
  mainnet. The stand-in pools stay on chain, and the previous revision of this file in git keeps
19
19
  their ids; the tests publish their own stand-ins. Any Move change means a new publish and a new
@@ -2,9 +2,9 @@
2
2
  "network": "mainnet",
3
3
  "grpcUrl": "https://fullnode.mainnet.sui.io:443",
4
4
  "chainIdentifier": "4btiuiMPvEENsttpZC7CZ53DruC3MAgfznDbASZ7DR6S",
5
- "packageId": "0x4736026bde8ef425b243013e6e25431a9b5c9c5ccf62ff87ceb0d4e67c700a22",
6
- "publishedAt": "0x4736026bde8ef425b243013e6e25431a9b5c9c5ccf62ff87ceb0d4e67c700a22",
7
- "configId": "0x7d472b14c833c4d8442ac3a176e25d47e946847f293af58934ff2e3fb3109f7c",
5
+ "packageId": "0x389b58171d057852dd4b071d47474a2a97a6e4489cc2094a527a57d57d58063f",
6
+ "publishedAt": "0x389b58171d057852dd4b071d47474a2a97a6e4489cc2094a527a57d57d58063f",
7
+ "configId": "0xd300382e608b07f96796e707ab92253597fc4c199172cc35627aad6c2d243f2c",
8
8
  "coins": [
9
9
  {
10
10
  "type": "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI",
@@ -2,9 +2,9 @@
2
2
  "network": "testnet",
3
3
  "grpcUrl": "https://fullnode.testnet.sui.io:443",
4
4
  "chainIdentifier": "69WiPg3DAQiwdxfncX6wYQ2siKwAe6L9BZthQea3JNMD",
5
- "packageId": "0x52017f8e68e133c6dc84c8733a9f52de0d2a9fb5e2c63b8949b0f7c0c47917b6",
6
- "publishedAt": "0x52017f8e68e133c6dc84c8733a9f52de0d2a9fb5e2c63b8949b0f7c0c47917b6",
7
- "configId": "0xe58594af166a1280f9ab04d0e615ceb7209211bc9bee6780a4b00878b023a65b",
5
+ "packageId": "0xb6e9d01e6718cf1ccc33598efc892e1891f564f82824cd4af5b7d40160e21bf0",
6
+ "publishedAt": "0xb6e9d01e6718cf1ccc33598efc892e1891f564f82824cd4af5b7d40160e21bf0",
7
+ "configId": "0xe465c9fc3225454f16f2212136f6b2ccea2dc5d4168502b42bbdff548dbca7c8",
8
8
  "coins": [
9
9
  {
10
10
  "type": "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI",
@@ -12,7 +12,7 @@
12
12
  "decimals": 9
13
13
  },
14
14
  {
15
- "type": "0xd85020ee4adfa8137605184ad876c96ca293577533a37bff43ac2778b97f2938::usdc::USDC",
15
+ "type": "0x6829a10a5340763ad78735fea97f9e26c02cd774bb20cb1d12615b1e54e8deeb::usdc::USDC",
16
16
  "symbol": "USDC",
17
17
  "decimals": 6
18
18
  }
@@ -20,28 +20,28 @@
20
20
  "pools": [],
21
21
  "maxTermDays": 365,
22
22
  "demoFaucet": {
23
- "packageId": "0xd85020ee4adfa8137605184ad876c96ca293577533a37bff43ac2778b97f2938",
24
- "faucetId": "0x853a8e316634215fc297f07a3d23a98b4d40222a7819a07068737689d6c8fc00",
25
- "coin": "0xd85020ee4adfa8137605184ad876c96ca293577533a37bff43ac2778b97f2938::usdc::USDC"
23
+ "packageId": "0x6829a10a5340763ad78735fea97f9e26c02cd774bb20cb1d12615b1e54e8deeb",
24
+ "faucetId": "0xc93883668a3e6b44e8333936ea9e2817805be1f0d673a6887a78b3156e2e9ed4",
25
+ "coin": "0x6829a10a5340763ad78735fea97f9e26c02cd774bb20cb1d12615b1e54e8deeb::usdc::USDC"
26
26
  },
27
27
  "protocols": {
28
28
  "deepbook": {
29
- "packageId": "0xf6331717135b1e7edc75ba2cfb3b08a9ec8549884cfc18abc534e4a0bbada9e8",
30
- "publishedAt": "0xf6331717135b1e7edc75ba2cfb3b08a9ec8549884cfc18abc534e4a0bbada9e8"
29
+ "packageId": "0x5151e1122073b79c9aafeff11a10420d6c9c0d2d03a7428fa908ace0d368ebcb",
30
+ "publishedAt": "0x5151e1122073b79c9aafeff11a10420d6c9c0d2d03a7428fa908ace0d368ebcb"
31
31
  },
32
32
  "cetus": {
33
- "packageId": "0xffa6ea563e395f3fd3d86e227a59bdd0ed98ad23c2940822bf9c30c70ce1f167",
34
- "publishedAt": "0xffa6ea563e395f3fd3d86e227a59bdd0ed98ad23c2940822bf9c30c70ce1f167",
35
- "configId": "0x2105734227e38828ba69289d4cce4edc1e45666a717c692a9575b6d467ee3bef"
33
+ "packageId": "0x62618216842046496e2dfc46400a116558d474a595ccb1bfffbea0ba6e032885",
34
+ "publishedAt": "0x62618216842046496e2dfc46400a116558d474a595ccb1bfffbea0ba6e032885",
35
+ "configId": "0x1ba07f13168a8ce9016d4c11cf3c9e82b5750904d5ebd065b802d04e4497386c"
36
36
  },
37
37
  "navi": {
38
- "packageId": "0x5cacd4bed4e0502280b0fe94eb51e02244dea86b584e1f91d9ded493c72eebb5",
39
- "publishedAt": "0x5cacd4bed4e0502280b0fe94eb51e02244dea86b584e1f91d9ded493c72eebb5",
40
- "oraclePackageId": "0x4891910b7259bff2f220f017c7e7e4628f5c26efff47eeb75453cf997387a56b",
41
- "storageId": "0x37d8af65a9ac8ae7c4e99304ae8347ef72dcd30759f509f8c4376e86107087bc",
42
- "oracleId": "0x3730ff06112853476c9b8c6121206776c6ed912ecc61ce8ffe25b697250f0131",
43
- "incentiveV2Id": "0xb776dbb5e7a27a766d8fb4087000d58831eec3061a30c95edc5c728ef1508407",
44
- "incentiveV3Id": "0xbafebe7c1a71f024f304f626215f6706c40cff72c45163e09d62d97cadea4f9e",
38
+ "packageId": "0xac15f2796ef5484dc66e0ffe17464c9858f0b5d8cd199a05f0346dda0e0f6ab2",
39
+ "publishedAt": "0xac15f2796ef5484dc66e0ffe17464c9858f0b5d8cd199a05f0346dda0e0f6ab2",
40
+ "oraclePackageId": "0xf817a7885d31650680d4eeb2e55220316f57f902a23a1648f3d469876463a45d",
41
+ "storageId": "0x073f220b58dd691ffa01505274677784472450ca845c813b3ee77fa8fc8654e3",
42
+ "oracleId": "0x8c9198b2eca4e9b08b456a23ba2c9862df34e06b350f3912320250dfd1cc235f",
43
+ "incentiveV2Id": "0xcc1b64820185219fe7554ea223a238aecece52733f772c76adcc94b2b68df60f",
44
+ "incentiveV3Id": "0x24c969a0d6006b7b5e9cb0920b9ade50ba8acbfb30f5d5d5928538feb1984a4e",
45
45
  "reserves": {}
46
46
  }
47
47
  }
package/dist/agent.js CHANGED
@@ -273,35 +273,64 @@ export async function quote(i, pair, amountIn) {
273
273
  return { pool, ...result };
274
274
  }
275
275
  /**
276
- * Sells `coinIn` for `coinOut` on a listed pool. Proceeds return to the owner, never to the
277
- * agent. The pool decides the entry and its direction: DeepBook base to quote or quote to base,
278
- * Cetus a to b or b to a. Without `poolId`, the first listed pool for the pair.
276
+ * Sells `coinIn` for `coinOut`. Proceeds return to the owner, never to the agent. One
277
+ * transaction: `begin_swap` charges the allowance and the rule, one call per pool carries the
278
+ * coins through it, and `finish_swap` checks the output against `minOut` and the owner's
279
+ * floor. `route` names the pools in order, for a pair with no pool of its own (sell TAKE for
280
+ * USDC through TAKE/SUI, then SUI/USDC): the coins in the middle never rest anywhere and need
281
+ * no allowance. Without `route`, one listed pool for the pair, by `poolId` or `venue`, else the
282
+ * first.
279
283
  */
280
284
  export function swap(i, pair, amountIn, minOut) {
281
285
  const d = i.deployment, tx = new Transaction();
282
- const pool = poolFor(i, pair);
283
- const forward = sameCoin(pool.coinA, pair.coinIn);
284
- const entry = pool.venue === 'deepbook'
285
- ? forward
286
- ? 'deepbook_base_to_quote'
287
- : 'deepbook_quote_to_base'
288
- : forward
289
- ? 'cetus_a_to_b'
290
- : 'cetus_b_to_a';
291
- const market = pool.venue === 'deepbook'
292
- ? [tx.object(pool.poolId)]
293
- : [tx.object(d.protocols.cetus.configId), tx.object(pool.poolId)];
294
- tx.moveCall({
295
- target: `${d.publishedAt}::pass::${entry}`,
296
- typeArguments: [pool.coinA, pool.coinB],
286
+ const route = pair.route
287
+ ? pair.route.map((id) => {
288
+ const pool = d.pools.find((p) => p.poolId === normalizeSuiAddress(id));
289
+ if (!pool)
290
+ throw new Error(`${id} is not a pool this pass lists`);
291
+ return pool;
292
+ })
293
+ : [poolFor(i, pair)];
294
+ const pass_ = tx.object(i.active.passId);
295
+ let swap = tx.moveCall({
296
+ target: `${d.publishedAt}::pass::begin_swap`,
297
+ typeArguments: [pair.coinIn, pair.coinOut],
297
298
  arguments: [
298
- ...pass(tx, i),
299
+ pass_,
300
+ tx.object(d.configId),
299
301
  ...funds(tx, i, pair.coinIn, amountIn),
300
- ...market,
301
- tx.pure.u64(minOut),
302
302
  tx.object(CLOCK),
303
303
  ],
304
304
  });
305
+ let held = normalizeStructTag(pair.coinIn);
306
+ for (const pool of route) {
307
+ const forward = sameCoin(pool.coinA, held);
308
+ if (!forward && !sameCoin(pool.coinB, held))
309
+ throw new Error(`Pool ${pool.poolId} does not trade ${held}`);
310
+ const entry = pool.venue === 'deepbook'
311
+ ? forward
312
+ ? 'deepbook_base_to_quote'
313
+ : 'deepbook_quote_to_base'
314
+ : forward
315
+ ? 'cetus_a_to_b'
316
+ : 'cetus_b_to_a';
317
+ const market = pool.venue === 'deepbook'
318
+ ? [tx.object(pool.poolId), tx.object(CLOCK)]
319
+ : [tx.object(d.protocols.cetus.configId), tx.object(pool.poolId), tx.object(CLOCK)];
320
+ swap = tx.moveCall({
321
+ target: `${d.publishedAt}::pass::${entry}`,
322
+ typeArguments: [pair.coinIn, pair.coinOut, pool.coinA, pool.coinB],
323
+ arguments: [pass_, swap, ...market],
324
+ });
325
+ held = normalizeStructTag(forward ? pool.coinB : pool.coinA);
326
+ }
327
+ if (!sameCoin(held, pair.coinOut))
328
+ throw new Error(`The route ends in ${held}, not ${pair.coinOut}`);
329
+ tx.moveCall({
330
+ target: `${d.publishedAt}::pass::finish_swap`,
331
+ typeArguments: [pair.coinIn, pair.coinOut],
332
+ arguments: [pass_, swap, tx.pure.u64(minOut)],
333
+ });
305
334
  return tx;
306
335
  }
307
336
  const reserve = (i, coin) => {
package/dist/describe.js CHANGED
@@ -7,15 +7,22 @@
7
7
  */
8
8
  import { bcs } from '@mysten/sui/bcs';
9
9
  import { fromBase64, normalizeSuiAddress } from '@mysten/sui/utils';
10
- import { limitDisplay, priceTerms, sameCoin, showCoin, SUI, } from './domain.js';
10
+ import { coinLabel, limitDisplay, priceTerms, sameCoin, showCoin, SUI, } from './domain.js';
11
11
  const healthFactor = (ray) => (Number(BigInt(ray) / 10n ** 25n) / 100).toFixed(2);
12
12
  /** The reviewed rules, or the installed policies once `live` is read from chain. */
13
13
  export function describePolicy(d, p, live = null) {
14
14
  const show = (coin, value) => showCoin(d, coin, value);
15
15
  const symbol = (coin) => d.coins.find((c) => sameCoin(c.type, coin))?.symbol ?? coin;
16
- const poolName = (id) => {
16
+ const poolName = (id, pair) => {
17
17
  const pool = d.pools.find((x) => x.poolId === id);
18
- return pool ? (pool.venue === 'deepbook' ? 'DeepBook' : 'Cetus') : id;
18
+ if (!pool)
19
+ return id;
20
+ const venue = pool.venue === 'deepbook' ? 'DeepBook' : 'Cetus';
21
+ // A pool of the pair itself needs no label; one on a route through other coins does.
22
+ const direct = pair &&
23
+ ((sameCoin(pool.coinA, pair[0]) && sameCoin(pool.coinB, pair[1])) ||
24
+ (sameCoin(pool.coinA, pair[1]) && sameCoin(pool.coinB, pair[0])));
25
+ return direct ? venue : `${venue} ${symbol(pool.coinA)}/${symbol(pool.coinB)}`;
19
26
  };
20
27
  const rows = [
21
28
  {
@@ -50,7 +57,9 @@ export function describePolicy(d, p, live = null) {
50
57
  label: terms.limit === 'max'
51
58
  ? `Buy ${symbol(sw.coinOut)} with ${symbol(sw.coinIn)} on`
52
59
  : `Sell ${symbol(sw.coinIn)} for ${symbol(sw.coinOut)} on`,
53
- value: (l?.venues ?? sw.pools).map(poolName).join(', '),
60
+ value: (l?.venues ?? sw.pools)
61
+ .map((id) => poolName(id, [sw.coinIn, sw.coinOut]))
62
+ .join(', '),
54
63
  }, {
55
64
  label: `Max ${symbol(sw.coinIn)} ${terms.limit === 'max' ? 'spent' : 'sold'} per trade / per UTC day`,
56
65
  value: `${show(sw.coinIn, l?.perTrade ?? sw.perTrade)} / ${show(sw.coinIn, l?.daily ?? sw.daily)}`,
@@ -135,6 +144,7 @@ const OWNER_ONLY = new Set([
135
144
  export function describeAttempt(d, sessionAddress, recipients, tx) {
136
145
  const { inputs, commands } = tx.transaction;
137
146
  const coin = (type, value) => type ? showCoin(d, normalizeType(type), value) : `${value} base units of an unknown coin`;
147
+ const symbolOf = (type) => type ? coinLabel(d, normalizeType(type)) : 'an unknown coin';
138
148
  const input = (arg) => arg && typeof arg === 'object' && 'Input' in arg
139
149
  ? inputs[arg.Input]
140
150
  : undefined;
@@ -205,18 +215,20 @@ export function describeAttempt(d, sessionAddress, recipients, tx) {
205
215
  recipient = pure(a[a.length - 2], 'string');
206
216
  what = `Pay ${amount(3)} to ${recipient ? `"${recipient}"` : 'a recipient'}`;
207
217
  break;
208
- case 'deepbook_base_to_quote':
209
- what = `Sell ${amount(3)} on ${venue(object(a[4]))}, accepting at least ${amount(5, t1)}`;
210
- break;
211
- case 'deepbook_quote_to_base':
212
- what = `Sell ${amount(3, t1)} on ${venue(object(a[4]))}, accepting at least ${amount(5)}`;
213
- break;
214
- case 'cetus_a_to_b':
215
- what = `Sell ${amount(3)} on ${venue(object(a[5]))}, accepting at least ${amount(6, t1)}`;
216
- break;
217
- case 'cetus_b_to_a':
218
- what = `Sell ${amount(3, t1)} on ${venue(object(a[5]))}, accepting at least ${amount(6)}`;
218
+ case 'begin_swap': {
219
+ // A route: begin_swap, one call per pool, finish_swap with the agent's min_out.
220
+ const hops = calls.filter((c) => [
221
+ 'deepbook_base_to_quote',
222
+ 'deepbook_quote_to_base',
223
+ 'cetus_a_to_b',
224
+ 'cetus_b_to_a',
225
+ ].includes(c.function));
226
+ const pools = hops.map((c) => venue(object(c.arguments[c.function.startsWith('cetus') ? 3 : 2])));
227
+ const end = calls.find((c) => c.function === 'finish_swap');
228
+ const floor = end ? pure(end.arguments[2], 'u64') : null;
229
+ what = `Sell ${amount(3)} for ${symbolOf(t1)} on ${pools.join(', then ') || 'no pool'}, accepting at least ${floor === null ? 'an amount' : coin(t1, floor)}`;
219
230
  break;
231
+ }
220
232
  case 'navi_supply':
221
233
  what = `Supply ${amount(3)} to NAVI`;
222
234
  break;
@@ -349,7 +361,7 @@ export function describeRefusal(d, error, recipient) {
349
361
  pass: {
350
362
  1: 'Not an allowance issued for this pass',
351
363
  2: 'No such object is held by the pass',
352
- 7: 'This entry was retired by a package upgrade; use the current SDK',
364
+ 7: 'A swap begun on one pass cannot end on another',
353
365
  },
354
366
  control: {
355
367
  0: 'Only your wallet can do this',
package/dist/domain.js CHANGED
@@ -221,6 +221,26 @@ export function coinBySymbol(d, symbol) {
221
221
  throw new Error(`No coin called ${symbol}; this deployment lists ${d.coins.map((x) => x.symbol).join(', ')}`);
222
222
  return c;
223
223
  }
224
+ /**
225
+ * Whether `pools` connect `coinIn` to `coinOut`: directly, or through other coins a route
226
+ * passes through in one transaction. A swap rule's pools must, or no trade could ever run.
227
+ */
228
+ export function connects(pools, coinIn, coinOut) {
229
+ const seen = new Set([normalizeStructTag(coinIn)]), queue = [normalizeStructTag(coinIn)];
230
+ while (queue.length) {
231
+ const at = queue.shift();
232
+ if (at === normalizeStructTag(coinOut))
233
+ return true;
234
+ for (const p of pools) {
235
+ const other = sameCoin(p.coinA, at) ? p.coinB : sameCoin(p.coinB, at) ? p.coinA : null;
236
+ if (other && !seen.has(normalizeStructTag(other))) {
237
+ seen.add(normalizeStructTag(other));
238
+ queue.push(normalizeStructTag(other));
239
+ }
240
+ }
241
+ }
242
+ return false;
243
+ }
224
244
  /** The pools that trade `coinIn` for `coinOut`, in either pool order. */
225
245
  export function poolsFor(d, coinIn, coinOut) {
226
246
  return d.pools.filter((p) => (sameCoin(p.coinA, coinIn) && sameCoin(p.coinB, coinOut)) ||
package/dist/mcp.js CHANGED
@@ -111,7 +111,8 @@ export async function venues(client, d) {
111
111
  coinA: pool.coinA,
112
112
  coinB: pool.coinB,
113
113
  pair: `${base}/${quote}`,
114
- entries: pool.venue === 'deepbook'
114
+ // Each pool is one hop of a route: begin_swap, these, finish_swap, in one transaction.
115
+ hops: pool.venue === 'deepbook'
115
116
  ? {
116
117
  [`${base}→${quote}`]: 'pass::deepbook_base_to_quote',
117
118
  [`${quote}→${base}`]: 'pass::deepbook_quote_to_base',
package/dist/plugin.js CHANGED
@@ -22,7 +22,7 @@ import { fromBase64, normalizeSuiAddress } from '@mysten/sui/utils';
22
22
  import { z } from 'zod';
23
23
  import { clientFor, deepbookSizes, findPools, quoteSwap, readAllHoldings, readHoldings, readStatus, withMarketFacts, } from './chain.js';
24
24
  import { describePolicy, describeSetup, renderRows } from './describe.js';
25
- import { address, coinBySymbol, coinInfo, DAY_MS, defaultGasDaily, DeploymentSchema, display, isStable, limitUnits, MAX_TERM_DAYS, poolsFor, recipientName, requiredSui, sameCoin, SetupSchema, showCoin, SUI, uncovered, units, VenueSchema, } from './domain.js';
25
+ import { address, coinBySymbol, coinInfo, connects, DAY_MS, defaultGasDaily, DeploymentSchema, display, isStable, limitUnits, MAX_TERM_DAYS, poolsFor, recipientName, requiredSui, sameCoin, SetupSchema, showCoin, SUI, uncovered, units, VenueSchema, } from './domain.js';
26
26
  import { passIdOf } from './explorer.js';
27
27
  import { passEnded, returnGasFloat } from './float.js';
28
28
  import { failure, INSTRUCTIONS, keyAlert, MAX_TOOL_INPUT_ELEMENTS, registerDocs, result, serverInfo, sessionInfo, SIGN_ANNOTATIONS, SIGN_DESCRIPTION, } from './mcp.js';
@@ -59,11 +59,18 @@ class Registry {
59
59
  }
60
60
  /** Sessions on disk this code cannot open, with what their files still say about the pass. */
61
61
  unreadable = new Map();
62
+ /**
63
+ * Every session on disk, each re-read: another process (the one whose watcher saw the owner
64
+ * sign, a later connect) may have changed a session file since this one loaded it.
65
+ */
62
66
  async all() {
63
67
  await mkdir(this.sessionsDir, { recursive: true, mode: 0o700 });
64
68
  for (const id of (await readdir(this.sessionsDir)).sort()) {
65
- if (this.sessions.has(id))
69
+ const known = this.sessions.get(id);
70
+ if (known) {
71
+ await known.store.refresh().catch(() => { });
66
72
  continue;
73
+ }
67
74
  try {
68
75
  this.sessions.set(id, {
69
76
  id,
@@ -233,7 +240,7 @@ const rulesInput = {
233
240
  pools: z
234
241
  .array(address)
235
242
  .optional()
236
- .describe('pool ids from find_pools for a pair the network does not list; never ask the owner for one. Verified on chain'),
243
+ .describe('pool ids from find_pools: the pools a trade may go through, directly or as a route through other coins (sell TAKE for USDC through TAKE/SUI then SUI/USDC); the coins in the middle need no rule and no allowance. Never ask the owner for one. Verified on chain'),
237
244
  perTrade: decimal.describe('sold coin per trade'),
238
245
  daily: decimal.describe('sold coin per UTC day'),
239
246
  limitPrice: decimal.describe("the owner's price limit. With a stablecoin on one side it is that stablecoin per one of the other coin: the most paid when buying, the least accepted when selling. Otherwise it is bought coin per one sold coin, the least accepted. Required, above 0, and only the owner sets it: ask them, showing the pool's current price from list_passes"),
@@ -309,11 +316,14 @@ async function toSetup(client, d0, input) {
309
316
  })),
310
317
  swaps: input.swaps.map((sw) => {
311
318
  const coinIn = coin(sw.sell).type, coinOut = coin(sw.buy).type;
312
- const pools = poolsFor(d, coinIn, coinOut).filter((p) => (!sw.venues || sw.venues.includes(p.venue)) &&
313
- (!sw.pools || sw.pools.some((id) => normalizeSuiAddress(id) === p.poolId)));
314
- if (!pools.length)
319
+ // Named pools may form a route through other coins; otherwise the listed pools for
320
+ // the pair itself, narrowed by venue.
321
+ const pools = sw.pools
322
+ ? d.pools.filter((p) => sw.pools.some((id) => normalizeSuiAddress(id) === p.poolId))
323
+ : poolsFor(d, coinIn, coinOut).filter((p) => !sw.venues || sw.venues.includes(p.venue));
324
+ if (!pools.length || !connects(pools, coinIn, coinOut))
315
325
  throw new Error(d.pools.length
316
- ? `No pool trades ${sw.sell} for ${sw.buy}${sw.venues ? ` on ${sw.venues.join(', ')}` : ''}${sw.pools ? ` among ${sw.pools.join(', ')}` : ''}; look one up with find_pools and pass its id in pools`
326
+ ? `No pool${sw.pools ? ' among those named' : ''} trades ${sw.sell} for ${sw.buy}${sw.venues ? ` on ${sw.venues.join(', ')}` : ''}, directly or through other coins; look pools up with find_pools and pass their ids in pools`
317
327
  : `Swaps are not offered on ${d.network}: it lists no pools. Propose a pass on a network that does, or leave swaps out`);
318
328
  return {
319
329
  coinIn,
package/dist/server.js CHANGED
@@ -219,7 +219,10 @@ export async function startServer(store, port = 0) {
219
219
  sessionAddress: store.state.sessionAddress,
220
220
  setup: store.state.setup,
221
221
  }),
222
- passUrl: store.state.active ? passPageUrl(d, origin, store.state.active.passId) : null,
222
+ // Read on use: the activation that makes a pass page exist lands after the server starts.
223
+ get passUrl() {
224
+ return store.state.active ? passPageUrl(d, origin, store.state.active.passId) : null;
225
+ },
223
226
  mcpUrl: `${origin}/mcp`,
224
227
  close: () => new Promise((resolve, reject) => {
225
228
  closed = true;
package/docs/AGENT.md CHANGED
@@ -45,9 +45,9 @@ try {
45
45
 
46
46
  Builders take the identity (`agent.identity`), a coin as its full type string (`session_info.coins`
47
47
  lists each coin with its symbol and decimals) and base units (`units('0.1', 9)` for SUI):
48
- `send(i, coin, amount, recipientName)`, `swap(i, { coinIn, coinOut, poolId?, venue? }, amountIn, minOut)`
49
- on a listed pool (the first pool for the pair when none is named; the pool's order decides
50
- the entry and direction), `supply(i, coin, amount)`, `await withdraw(i, coin, amount)`,
48
+ `send(i, coin, amount, recipientName)`, `swap(i, { coinIn, coinOut, poolId?, venue?, route? }, amountIn, minOut)`
49
+ on one listed pool for the pair (the first when none is named), or along `route`, the rule's
50
+ pool ids in order, when the pair trades only through other coins, `supply(i, coin, amount)`, `await withdraw(i, coin, amount)`,
51
51
  `await borrow(i, coin, amount)`, `await repay(i, coin, amount)` (the three that check health first
52
52
  refresh NAVI's oracle prices, which on mainnet must be newer than its update interval), `stake(i, amount, validator)` in SUI with
53
53
  `await pickValidator(i)` for the validator, `unstake(i, stakeId)` and `refillGas(i, amount)`. Each
@@ -167,17 +167,27 @@ window; `0x3::validator_set` 10 below the 1 SUI minimum stake.
167
167
 
168
168
  ## The pass
169
169
 
170
- | Function | Type arguments | Explicit arguments |
171
- | ---------------------------------------------------------------------------------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
172
- | `pass::transfer` | `[coin]` | pass, config, allowance, withdrawal, recipient name, clock |
173
- | `pass::deepbook_base_to_quote` / `deepbook_quote_to_base` | `[base, quote]` | pass, config, allowance, withdrawal, a DeepBook pool from `deployment.pools` (`coinA` is base, `coinB` quote), min_out, clock |
174
- | `pass::cetus_a_to_b` / `cetus_b_to_a` | `[a, b]` | pass, config, allowance, withdrawal, `protocols.cetus.configId`, a Cetus pool from `deployment.pools`, min_out, clock |
175
- | `pass::navi_supply` | `[coin]` | pass, config, allowance, withdrawal, `navi.storageId`, `navi.reserves[coin].poolId`, `navi.reserves[coin].assetId`, `navi.incentiveV2Id`, `navi.incentiveV3Id`, clock |
176
- | `pass::navi_withdraw` / `navi_borrow` | `[coin]` | pass, config, `navi.oracleId`, storage, pool, asset, incentiveV2, incentiveV3, `0x5`, amount, clock |
177
- | `pass::navi_repay` | `[coin]` | pass, config, allowance, withdrawal, oracle, storage, pool, asset, incentiveV2, incentiveV3, clock |
178
- | `pass::stake` | | pass, config, SUI allowance, withdrawal, `0x5`, validator address, clock; returns the stake's ID |
179
- | `pass::unstake` | | pass, config, `0x5`, stake ID, clock |
180
- | `pass::add_policy`, `remove_policy`, `set_term`, `revoke_agent`, `deposit_object`, `withdraw_object`, `navi_open`, `destroy` | | **owner sender only**; installs take `config` after the pass, exits do not |
170
+ | Function | Type arguments | Explicit arguments |
171
+ | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
172
+ | `pass::transfer` | `[coin]` | pass, config, allowance, withdrawal, recipient name, clock |
173
+ | `pass::begin_swap` | `[in, out]` | pass, config, allowance, withdrawal, clock; returns the route (`Swap<in, out, in>`), a hot potato the transaction must end with `finish_swap` |
174
+ | `pass::deepbook_base_to_quote` / `deepbook_quote_to_base` | `[in, out, base, quote]` | pass, the route, a DeepBook pool from the rule's pools (`coinA` is base, `coinB` quote), clock; returns the route holding the other coin |
175
+ | `pass::cetus_a_to_b` / `cetus_b_to_a` | `[in, out, a, b]` | pass, the route, `protocols.cetus.configId`, a Cetus pool from the rule's pools, clock; returns the route holding the other coin |
176
+ | `pass::finish_swap` | `[in, out]` | pass, the route holding `out`, min_out; checks the agent's min_out and the owner's floor on the whole route and sends `out` to the owner |
177
+ | `pass::navi_supply` | `[coin]` | pass, config, allowance, withdrawal, `navi.storageId`, `navi.reserves[coin].poolId`, `navi.reserves[coin].assetId`, `navi.incentiveV2Id`, `navi.incentiveV3Id`, clock |
178
+ | `pass::navi_withdraw` / `navi_borrow` | `[coin]` | pass, config, `navi.oracleId`, storage, pool, asset, incentiveV2, incentiveV3, `0x5`, amount, clock |
179
+ | `pass::navi_repay` | `[coin]` | pass, config, allowance, withdrawal, oracle, storage, pool, asset, incentiveV2, incentiveV3, clock |
180
+ | `pass::stake` | | pass, config, SUI allowance, withdrawal, `0x5`, validator address, clock; returns the stake's ID |
181
+ | `pass::unstake` | | pass, config, `0x5`, stake ID, clock |
182
+ | `pass::add_policy`, `remove_policy`, `set_term`, `revoke_agent`, `deposit_object`, `withdraw_object`, `navi_open`, `destroy` | | **owner sender only**; installs take `config` after the pass, exits do not |
183
+
184
+ A swap is a route in one transaction: `begin_swap` charges the allowance and the `SwapPolicy<in,
185
+ out>` with the whole input, each pool call carries the coins through that pool (the route's
186
+ third type argument is the coin it holds, so the calls only chain in an order the types allow),
187
+ and `finish_swap` accepts the route only once it holds `out`. Every pool must be on the rule's
188
+ list; a coin in the middle never rests anywhere and needs no allowance and no rule. What a pool
189
+ leaves unspent goes to the owner, and unspent input gets its budget back. A route begun on one
190
+ pass cannot end on another (`pass` abort 7).
181
191
 
182
192
  A pass's ID is derived from the `Config` and its agent key: `pass::pass_of(config, agent)` on
183
193
  chain, `passIdOf(deployment, agent)` in the client. A key has one pass, ever.
package/docs/PLAYBOOK.md CHANGED
@@ -49,9 +49,14 @@ other pairs it is the bought coin per one sold coin, the least accepted. The lim
49
49
  the owner signs, so a limit close to the market refuses every trade once the price moves past
50
50
  it; say so when the owner picks one.
51
51
 
52
- **Venues.** DeepBook fills nothing under a pool's minimum order (1 SUI on the mainnet SUI/USDC
53
- pool), so list Cetus as well when trades will be small. A network may list no pools or no NAVI
54
- reserves; `list_passes` says so, and swap or lending rules are refused there.
52
+ **Venues and routes.** A swap rule lists the pools a trade may go through. When the pair has
53
+ no pool of its own, or that pool is too shallow, list the pools of a route through another
54
+ coin: to sell TAKE for USDC, the TAKE/SUI and SUI/USDC pools. One rule, one allowance, for the
55
+ coin sold; the coin in the middle never rests anywhere and needs no rule and no allowance of
56
+ its own. Never propose a rule or an allowance for a coin only because a route passes through
57
+ it. DeepBook fills nothing under a pool's minimum order (1 SUI on the mainnet SUI/USDC pool), so
58
+ list Cetus as well when trades will be small. A network may list no pools or no NAVI reserves;
59
+ `list_passes` says so, and swap or lending rules are refused there.
55
60
 
56
61
  **Coins and pools.** The coins and pools `list_passes` shows for a network are the ones this
57
62
  package lists, not the only ones it can use. Name a listed coin by symbol, and any other coin the
@@ -170,7 +175,10 @@ const out = await agent.submit(send(agent.identity, usdc.type, units('5', usdc.d
170
175
  touching an allowance: `amountIn` is what the pool would take and `amountOut` what comes back.
171
176
  Set `minOut` a little under `amountOut`, never from a mid price; the owner's price limit still
172
177
  applies underneath. DeepBook takes its fee from the input and rounds down to its lot size, so
173
- sell at least one lot over its minimum.
178
+ sell at least one lot over its minimum. A route is one `swap` call with `route`, the rule's
179
+ pool ids in order; quote each leg in turn, feeding one leg's `amountOut` into the next, and set
180
+ `minOut` on the final coin. The chain runs the whole route in one transaction and checks the
181
+ owner's price limit on what went in against what came out.
174
182
 
175
183
  **Repayments.** Size a repayment from the live debt: an over-payment returns to the owner but
176
184
  still counts against the allowance.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mysten-incubation/sui-agent-pass",
3
- "version": "0.1.12",
3
+ "version": "0.1.14",
4
4
  "type": "module",
5
5
  "description": "AI builds transactions. A session signer signs. Your pass enforces the rules.",
6
6
  "repository": {
@@ -54,9 +54,14 @@ other pairs it is the bought coin per one sold coin, the least accepted. The lim
54
54
  the owner signs, so a limit close to the market refuses every trade once the price moves past
55
55
  it; say so when the owner picks one.
56
56
 
57
- **Venues.** DeepBook fills nothing under a pool's minimum order (1 SUI on the mainnet SUI/USDC
58
- pool), so list Cetus as well when trades will be small. A network may list no pools or no NAVI
59
- reserves; `list_passes` says so, and swap or lending rules are refused there.
57
+ **Venues and routes.** A swap rule lists the pools a trade may go through. When the pair has
58
+ no pool of its own, or that pool is too shallow, list the pools of a route through another
59
+ coin: to sell TAKE for USDC, the TAKE/SUI and SUI/USDC pools. One rule, one allowance, for the
60
+ coin sold; the coin in the middle never rests anywhere and needs no rule and no allowance of
61
+ its own. Never propose a rule or an allowance for a coin only because a route passes through
62
+ it. DeepBook fills nothing under a pool's minimum order (1 SUI on the mainnet SUI/USDC pool), so
63
+ list Cetus as well when trades will be small. A network may list no pools or no NAVI reserves;
64
+ `list_passes` says so, and swap or lending rules are refused there.
60
65
 
61
66
  **Coins and pools.** The coins and pools `list_passes` shows for a network are the ones this
62
67
  package lists, not the only ones it can use. Name a listed coin by symbol, and any other coin the
@@ -175,7 +180,10 @@ const out = await agent.submit(send(agent.identity, usdc.type, units('5', usdc.d
175
180
  touching an allowance: `amountIn` is what the pool would take and `amountOut` what comes back.
176
181
  Set `minOut` a little under `amountOut`, never from a mid price; the owner's price limit still
177
182
  applies underneath. DeepBook takes its fee from the input and rounds down to its lot size, so
178
- sell at least one lot over its minimum.
183
+ sell at least one lot over its minimum. A route is one `swap` call with `route`, the rule's
184
+ pool ids in order; quote each leg in turn, feeding one leg's `amountOut` into the next, and set
185
+ `minOut` on the final coin. The chain runs the whole route in one transaction and checks the
186
+ owner's price limit on what went in against what came out.
179
187
 
180
188
  **Repayments.** Size a repayment from the live debt: an over-payment returns to the owner but
181
189
  still counts against the allowance.