@puppet.fund/operator 0.1.0 → 0.2.0

package/README.md

@@ -24,36 +24,39 @@ The package is split by operator, so you choose yours:
 
 - **`@puppet.fund/operator/gmx`** — the ready-made GMX V2 venue (`gmxOperator(core)`), wrapping a
   core you build. What the scaffolder sets up, and what most users want.
-- **`@puppet.fund/operator`** — the generic, venue-agnostic core. `createOperatorCore(config)`
-  gives you pairing + endpoint resolution, the RPC/indexer clients, account + fund prediction and
+- **`@puppet.fund/operator`** — the generic, venue-agnostic core. `pairOverBrowser()` →
+  `createOperatorCore(session)` gives you the RPC client, account + fund prediction and
   deploy checks, the matchmaker compact, the generic `operate(callList)` dispatch,
-  `getFundBalance()`, and connection lifecycle (`status` / `isOpen()` / `close()`). Compose it
+  `getFundBalance()`, and connection lifecycle (`onStatus()` / `isOpen()` / `close()`). Compose it
   with your own venue call shapes to build an extended operator — a different venue, base token,
   or surface. The GMX venue is built on exactly this. Also here: `runOperator`,
-  `pairOverBrowser`, `createCompact`, `TOKEN_ID`, and the compact error helpers. Type your
+  `pairOverBrowser`, `buildSession`, `createCompact`, `TOKEN_ID`, and the compact error helpers. Type your
   operator against `IOperatorCore`.
 
 ## Usage
 
-Build the **core** (the connection — pairing/endpoint resolution, signing, the matchmaker compact,
-your account + fund, lifecycle), then wrap it in the GMX venue. The core does the async setup and
-owns the connection; `gmxOperator(core)` is synchronous and adds only GMX execution + reads — so
-you call connection/account actions on `core`, GMX actions on `gmx`. When you pair, the site hands
-over its matchmaker/indexer endpoints, so a paired operator needs no URL config; RPC defaults to
-the public Arbitrum endpoint (set `rpcUrl` for anything beyond a first run). GMX runs on a WETH
-fund (collateral and the keeper fee are the same token), so create your account and allocate a
-WETH fund on the site first.
+`pairOverBrowser()` returns the **session** — the whole sealed identity (account params, the fund
+and its base token, the matchmaker endpoint, the token registry). Pass it to `createOperatorCore`
+to build the **core** (signing, the matchmaker compact, your account + fund, lifecycle), then wrap
+it in the GMX venue. The core does the async setup and owns the connection; `gmxOperator(core)` is
+synchronous and adds only GMX execution + reads — so you call connection/account actions on `core`,
+GMX actions on `gmx`. RPC defaults to the public Arbitrum endpoint (set `rpcUrl` beyond a first
+run). The agent trades whatever base the paired fund settles in (the session names it) — WETH is
+the simplest (GMX's keeper fee is the same token, carved straight from the collateral, so the fund
+needs no native ETH); USDC or native ETH work too, but a non-WETH base also needs a little ETH in
+the fund for the GMX execution fee.
 
 ```ts
-import { createOperatorCore, runOperator } from '@puppet.fund/operator'
-import { GMX_BASE_TOKEN_ID, gmxOperator } from '@puppet.fund/operator/gmx'
+import { createOperatorCore, pairOverBrowser, runOperator } from '@puppet.fund/operator'
+import { gmxOperator } from '@puppet.fund/operator/gmx'
 
-// Zero-config: endpoints + session key arrive over the pairing tunnel.
-const core = await createOperatorCore({ baseTokenId: GMX_BASE_TOKEN_ID })
+// Pairing carries everything: identity, fund + base token, matchmaker endpoint, registry.
+const session = await pairOverBrowser() // a PAIR_URL for a local site, else https://puppet.fund
+const core = await createOperatorCore(session, { rpcUrl: Bun.env.ARBITRUM_RPC_URL })
 const gmx = gmxOperator(core)
 
-// Override endpoints by passing matchmakerUrl / indexerUrl / rpcUrl to createOperatorCore,
-// or add signerKey + user (with matchmakerUrl + indexerUrl) to run headless without pairing.
+// Headless (no browser): build the session yourself —
+// buildSession({ signerKey, user, baseTokenId, name }) — then createOperatorCore(session).
 
 const deployable = await core.getFundBalance() // core: account + connection
 const positions = await gmx.getPositions() //      gmx:  venue reads
@@ -80,25 +83,30 @@ Two addresses matter, both deterministic and printed at startup:
 
 ## Surface
 
-- `createOperatorCore(config)` (async, package root) — pairs / resolves endpoints, sets up the
-  matchmaker compact, predicts + checks the account and the fund, and returns the connection +
-  account surface you call directly: `getFundBalance()` (live base in the fund),
-  `getFundSignedBalance()` (the signed portion, on-chain), `isOpen()` (is the matchmaker
-  connected — gate a tick on it), `status`, `operate(callList, transferList?)` (the generic
-  signed-call dispatch under the venue surface — declare value the calls move as transfer legs;
-  the default 0/0 leg fits value-neutral dispatches, and the protocol attestor co-signs only
-  calls inside the venue perimeter it can screen, so arbitrary targets are rejected), and
-  `close()`; plus `account`, `fund`, `signer`,
-  `user`, `token`, `baseTokenId`, `publicClient`, `sql`, `compact`. Type it as `IOperatorCore`.
-  `matchmakerUrl` / `indexerUrl` are optional (a paired operator receives them from the site; pass
-  them to override, or supply both with `signerKey` + `user` to run headless). `rpcUrl` defaults
-  to the public Arbitrum endpoint. `dryRun: true` runs every dispatch through the identical
-  local verification + venue screen the matchmaker applies, logs what would be sent, and skips
-  the dispatch — the way to watch a strategy decide without risking funds. The session signer
-  stays private to the core — you get signed intents, not the key.
-- `gmxOperator(core, opts?)` (sync, `@puppet.fund/operator/gmx`) — the GMX venue over a core. Build
-  the core with `baseTokenId: GMX_BASE_TOKEN_ID` (WETH) and pass it in; this validates the base token
-  and adds GMX-only surface. Reads: `getMarket(indexToken)` (the canonical perp for the base token;
+- `pairOverBrowser(pairUrl?)` (async, package root) — opens a one-time `127.0.0.1` listener and
+  prints a link to open on the site; returns the sealed `IPairedSession`: `params` ({user,
+  signer}), `share` ({master, baseTokenId, name}), `matchmakerUrl`, and the token registry. For
+  unattended runs build the same shape with `buildSession({ signerKey, user, baseTokenId, name })`.
+- `createOperatorCore(session, config?)` (async, package root) — takes a session, sets up the
+  matchmaker compact, predicts + checks the account and the fund (asserting the session's
+  identity is internally consistent), and returns the connection + account surface you call
+  directly: `getFundBalance()` (live base in the fund), `getFundSignedBalance()` (the signed
+  portion, on-chain), `isOpen()` (is the matchmaker connected — gate a tick on it), `onStatus()`,
+  `operate(callList, transferList?)` (the generic signed-call dispatch under the venue surface —
+  declare value the calls move as transfer legs; the default 0/0 leg fits value-neutral
+  dispatches, and the protocol attestor co-signs only calls inside the venue perimeter it can
+  screen, so arbitrary targets are rejected), and `close()`; plus `params`, `share`, `account`,
+  `fund`, `signer`, `user`, `token`, `baseTokenId`, `publicClient`, `compact`. Type it as
+  `IOperatorCore`. The base token is the paired fund's (`share.baseTokenId`); the matchmaker
+  endpoint and registry come from the session too. The operator needs no indexer: intent block
+  anchors arrive as head frames on the relay socket, balances and settlement are read from the
+  chain. `config.rpcUrl` defaults to the public Arbitrum endpoint. `config.dryRun: true` runs
+  every dispatch through the identical local verification + venue screen the matchmaker applies,
+  logs what would be sent, and skips the dispatch — the way to watch a strategy decide without
+  risking funds. The session signer stays private to the core — you get signed intents, not the key.
+- `gmxOperator(core, opts?)` (sync, `@puppet.fund/operator/gmx`) — the GMX venue over a core whose
+  fund settles in a GMX-tradable base (WETH is simplest; `GMX_BASE_TOKEN_ID` is its id). Adds
+  GMX-only surface. Reads: `getMarket(indexToken)` (the canonical perp for the base token;
   throws only if still ambiguous), `getPositions(account?)` (defaults to your fund; pass any GMX
   account to read someone else's), `getOrders(account?)`, `markets`. Writes: `createOrder(...)` —
   the one primitive for every increase/decrease order type (market/limit/stop/take-profit) via
@@ -110,19 +118,18 @@ Two addresses matter, both deterministic and printed at startup:
   (size/collateral/margin incl. unrealized PnL, valuing WETH or USDC collateral correctly).
   `opts.executionFeeBufferBps` (default 2000 = 20%) pads the auto-quote. It does NOT re-expose
   core methods — call those on `core`.
-- Lifecycle + building blocks (`runOperator`, `pairOverBrowser`, `createCompact`, `TOKEN_ID`, compact
-  types + error helpers) live at the package root — see **Entrypoints** above. A GMX operator is
-  `createOperatorCore({ baseTokenId: GMX_BASE_TOKEN_ID })` + `gmxOperator(core)`, run under
-  `runOperator(core, body)`.
+- Lifecycle + building blocks (`runOperator`, `pairOverBrowser`, `buildSession`, `createCompact`,
+  `TOKEN_ID`, compact types + error helpers) live at the package root — see **Entrypoints** above.
+  A GMX operator is `pairOverBrowser()` → `createOperatorCore(session)` → `gmxOperator(core)`, run
+  under `runOperator(core, body)`.
 
 ## Pairing
 
-Without a `signerKey`, the core opens a one-time `127.0.0.1` listener and prints a link you
-open on the site. The browser seals your session key — and the site's matchmaker/indexer
-endpoints — to an ephemeral key in that link and posts it back. The key reaches the operator in
-memory only, never written to disk; the endpoints come from the site you're pairing with. Your
-account and fund must already exist (create the account and allocate a WETH fund on the site
-first).
+`pairOverBrowser()` opens a one-time `127.0.0.1` listener and prints a link you open on the site.
+The browser seals the session — your session key, the fund identity (`params` + `share`), the
+matchmaker endpoint, and the token registry — to an ephemeral key in that link and posts it back.
+The key reaches the operator in memory only, never written to disk. Your account and fund must
+already exist (create the account and allocate the fund on the site first).
 
 The browser seals the *derived* session key, never your wallet's bind signature, so a
 paired operator can sign operate intents but cannot deploy accounts under you.

package/dist/{core-DC0-qJhv.d.ts → core-DlV1H6H-.d.ts}

@@ -1,6 +1,4 @@
 import { Address, Hex, PublicClient } from "viem";
-import { IStream } from "aelea/stream";
-import { Client } from "graphql-ws";
 //#region ../contracts/dist/types/types/index.d.ts
 interface IAccount__CreatePuppetAccountIntent {
   params: IAccountLib__AccountInitParams;
@@ -181,16 +179,28 @@ interface ISubscribe__SubscribeIntent {
 //#endregion
 //#region ../contracts/dist/types/const/index.d.ts
 declare const TOKEN_ID: {
+  readonly ETH: '0xaaaebeba3810b1e6b70781f14b2d72c1cb89c0b2b320c43bb67ff79f562f5ff4';
   readonly USDC: '0xd6aca1be9729c13d677335161321649cccae6a591554772516700f986f942eaa';
   readonly WETH: '0x0f8a193ff464434486c0daf7db2a895884365d2bc84ba47a68fcf89c1b14b5b8';
 };
 //#endregion
-//#region ../sdk/dist/types/state/shared.d.ts
-interface IIndexerClient {
-  httpEndpoint: string;
-  wsClient: Client;
+//#region ../../indexer/script/__generated/entities.d.ts
+interface IRegisterToken__RegisterToken {
+  id: string;
+  chainId: bigint;
+  tokenId: Hex;
+  token: Address;
+  cap: bigint;
+  hubToken: Address;
+  blockTimestamp: number;
+  blockNumber: bigint;
+  logIndex: number;
+  transactionHash: Hex;
 }
 //#endregion
+//#region ../sdk/dist/types/state/tokenRegistry.d.ts
+type ITokenInfo = IRegisterToken__RegisterToken;
+//#endregion
 //#region ../sdk/dist/types/attestation/shared.d.ts
 interface IIntentByKind {
   subscribe: ISubscribe__SubscribeIntent;
@@ -433,21 +443,24 @@ type IRelayRequest<K extends IActionKind = IActionKind> = K extends IActionKind
   intent: IIntentByKind[K];
   signature: Hex;
 } : never;
-interface IAttestResult {
+interface IDispatchedFrame {
+  chainId: bigint;
+  account: Address;
+  nonce: bigint;
   txHash: Hex;
   actualRelayFee: bigint;
 }
 type IMatchmakerStatus = 'open' | 'connecting' | 'closed';
 interface ICompactOpts {
   matchmakerUrl: string;
-  sql: IIndexerClient;
   defaultTimeoutMs?: number;
-  settlementTimeoutMs?: number;
 }
 interface ICompact {
-  attest(request: IRelayRequest, timeoutMs?: number): Promise<IAttestResult>;
-  status: IStream<IMatchmakerStatus>;
+  attest(request: IRelayRequest, timeoutMs?: number): Promise<IDispatchedFrame>;
+  onStatus(cb: (status: IMatchmakerStatus) => void): () => void;
   isOpen(): boolean;
+  head(network: string): bigint | undefined;
+  awaitHead(network: string, timeoutMs?: number): Promise<bigint>;
   close(): void;
 }
 declare function createCompact(opts: ICompactOpts): ICompact;
@@ -2952,19 +2965,23 @@ declare function humanizeErrorCode(code: string): string;
 declare function humanizeContractError(code: string, args: readonly unknown[]): string;
 declare function formatThrownError(err: unknown): string;
 //#endregion
+//#region ../sdk/dist/types/account/pairing.d.ts
+interface IPairedSession {
+  signerKey: Hex;
+  params: IAccountLib__AccountInitParams;
+  share: IShareLib__ShareInitParams;
+  matchmakerUrl: string;
+  tokenRegistry?: ITokenInfo[];
+}
+//#endregion
 //#region src/core.d.ts
 interface IOperatorConfig {
-  baseTokenId: Hex;
-  matchmakerUrl?: string;
-  indexerUrl?: string;
   rpcUrl?: string;
-  user?: Address;
-  signerKey?: Hex;
-  siteUrl?: string;
-  pairPort?: number;
   dryRun?: boolean;
 }
 interface IOperatorCore {
+  params: IAccountLib__AccountInitParams;
+  share: IShareLib__ShareInitParams;
   user: Address;
   signer: Address;
   account: Address;
@@ -2972,15 +2989,16 @@ interface IOperatorCore {
   baseTokenId: Hex;
   token: Address;
   publicClient: PublicClient;
-  sql: IIndexerClient;
   compact: ICompact;
-  status: ICompact['status'];
+  onStatus: ICompact['onStatus'];
+  tokenIdFor: (token: Address) => Hex;
+  readSignedBalance: (tokenId: Hex) => Promise<bigint>;
   isOpen: () => boolean;
   getFundBalance: () => Promise<bigint>;
   getFundSignedBalance: () => Promise<bigint>;
-  operate: (callList: IIAccount__Call[], transferList?: IIAccount__SignTransfer[]) => Promise<IAttestResult>;
+  operate: (callList: IIAccount__Call[], transferList?: IIAccount__SignTransfer[]) => Promise<IDispatchedFrame>;
   close: () => void;
 }
-declare function createOperatorCore(config: IOperatorConfig): Promise<IOperatorCore>;
+declare function createOperatorCore(session: IPairedSession, config?: IOperatorConfig): Promise<IOperatorCore>;
 //#endregion
-export { CompactError as a, humanizeErrorCode as c, ICompactOpts as d, IMatchmakerStatus as f, CompactContractError as i, IAttestResult as l, TOKEN_ID as m, IOperatorCore as n, formatThrownError as o, createCompact as p, createOperatorCore as r, humanizeContractError as s, IOperatorConfig as t, ICompact as u };
+export { CompactContractError as a, humanizeContractError as c, ICompactOpts as d, IDispatchedFrame as f, TOKEN_ID as g, ITokenInfo as h, IPairedSession as i, humanizeErrorCode as l, createCompact as m, IOperatorCore as n, CompactError as o, IMatchmakerStatus as p, createOperatorCore as r, formatThrownError as s, IOperatorConfig as t, ICompact as u };

package/dist/gmx/index.d.ts

@@ -1,6 +1,5 @@
-import { l as IAttestResult, n as IOperatorCore } from "../core-DC0-qJhv.js";
+import { f as IDispatchedFrame, n as IOperatorCore } from "../core-DlV1H6H-.js";
 import { Address, Hex, PublicClient } from "viem";
-import { IStream } from "aelea/stream";
 //#region ../sdk/dist/types/venue/gmx.d.ts
 declare const GMX_ORDER_TYPE: {
   readonly MarketSwap: 0;
@@ -994,9 +993,9 @@ declare function gmxOperator(core: IOperatorCore, opts?: IGmxOptions): {
       _dataList: readonly `0x${string}`[];
     };
   }[]>;
-  createOrder: (p: IGmxOrder) => Promise<IAttestResult>;
-  cancelOrder(key: Hex): Promise<IAttestResult>;
-  updateOrder(p: IUpdateOrder): Promise<IAttestResult>;
+  createOrder: (p: IGmxOrder) => Promise<IDispatchedFrame>;
+  cancelOrder(key: Hex): Promise<IDispatchedFrame>;
+  updateOrder(p: IUpdateOrder): Promise<IDispatchedFrame>;
 };
 //#endregion
 export { GMX_BASE_TOKEN_ID, GMX_DECREASE_SWAP_TYPE, GMX_ORDER_TYPE, type IGasLimitsConfig, IGmxOptions, type IGmxOrder, IGmxPositionMetrics, IGmxPositionView, IUpdateOrder, acceptablePrice, calculateExecutionFee, dominantPosition, formatUsd, formatWeth, getGasLimitsConfig, getPositionPnlUsd, gmxOperator, gmxPrice, positionMetrics, usd, weth };

package/dist/gmx/index.js

@@ -1,5 +1,5 @@
-import { E as TOKEN_ID, S as CHAIN_TOKEN_MAP, d as applyFactor, f as ARBITRUM_MARKET_LIST, l as selectGmxMarket, n as GMX_INCREASE_TYPES, p as GMX_V2_CONTRACT_MAP, r as GMX_ORDER_TYPE, s as buildGmxOrderCalls, t as GMX_DECREASE_SWAP_TYPE, u as getPositionPnlUsd } from "../gmx-DwTiknYm.js";
-import { encodeFunctionData, formatUnits, isAddressEqual, parseUnits } from "viem";
+import { S as symbolForBaseTokenId, d as selectGmxMarket, f as getPositionPnlUsd, h as GMX_V2_CONTRACT_MAP, k as TOKEN_ID, l as buildGmxOrderCalls, m as ARBITRUM_MARKET_LIST, n as GMX_INCREASE_TYPES, p as applyFactor, r as GMX_ORDER_TYPE, t as GMX_DECREASE_SWAP_TYPE } from "../gmx-C0vgbHXM.js";
+import { encodeFunctionData, erc20Abi, formatUnits, getAddress, isAddressEqual, parseUnits, zeroAddress } from "viem";
 import { encodeAbiParameters as encodeAbiParameters$1, keccak256 as keccak256$1, parseAbiParameters } from "viem/utils";
 //#region ../sdk/dist/esm/gmx/gmxUtils.js
 function hashData(types, values) {
@@ -80,7 +80,6 @@ function positionMetrics(p, markPrice, longToken, shortTokenDecimals = 6) {
 	};
 }
 function gmxOperator(core, opts = {}) {
-	if (!isAddressEqual(core.token, CHAIN_TOKEN_MAP[42161].WETH)) throw new Error("gmxOperator needs a WETH-based core — create it with baseTokenId GMX_BASE_TOKEN_ID");
 	const { operate, publicClient, token, fund } = core;
 	const executionFeeBufferBps = opts.executionFeeBufferBps ?? 2000n;
 	let gasLimitsConfig = null;
@@ -91,20 +90,32 @@ function gmxOperator(core, opts = {}) {
 		return calculateExecutionFee(gasLimitsConfig, gasPrice, actionGasLimit) * (10000n + executionFeeBufferBps) / 10000n;
 	}
 	async function createOrder(p) {
-		const { callList, amountOut } = buildGmxOrderCalls(p, {
+		const { callList, outflows } = buildGmxOrderCalls(p, {
 			master: fund,
 			baseToken: token,
 			executionFee: p.executionFee ?? await quoteExecutionFee(p.orderType)
 		});
-		const [balance, signed] = await Promise.all([core.getFundBalance(), core.getFundSignedBalance()]);
-		if (balance < amountOut) throw new Error(`fund balance ${balance} below required ${amountOut} — allocate more on the site or size down`);
-		const surplus = balance > signed ? balance - signed : 0n;
-		return operate(callList, [{
-			tokenId: core.baseTokenId,
-			token,
-			amountIn: surplus,
-			amountOut
-		}]);
+		return operate(callList, await Promise.all(outflows.map(async (o) => {
+			const outToken = getAddress(o.token);
+			const tokenId = core.tokenIdFor(outToken);
+			const isNative = isAddressEqual(outToken, zeroAddress);
+			const [balance, signed] = await Promise.all([isNative ? publicClient.getBalance({ address: fund }) : publicClient.readContract({
+				address: outToken,
+				abi: erc20Abi,
+				functionName: "balanceOf",
+				args: [fund]
+			}), core.readSignedBalance(tokenId)]);
+			if (o.amountOut > balance) {
+				const sym = symbolForBaseTokenId(tokenId) ?? outToken;
+				throw new Error(`insufficient ${sym}: fund holds ${balance}, order needs ${o.amountOut} — allocate more on the site or size down`);
+			}
+			return {
+				tokenId,
+				token: outToken,
+				amountIn: balance > signed ? balance - signed : 0n,
+				amountOut: o.amountOut
+			};
+		})));
 	}
 	return {
 		GMX_ORDER_TYPE,