@mysten/deepbook-v3 1.6.7 → 2.0.0

package/src/contracts/margin_liquidation/liquidation_vault.ts

@@ -282,6 +282,7 @@ export interface LiquidateBaseOptions {
 		  ];
 	typeArguments: [string, string];
 }
+/** Twin: `liquidate_base_upgraded`. Edit both. */
 export function liquidateBase(options: LiquidateBaseOptions) {
 	const packageAddress = options.package ?? '@deepbook/margin-liquidation';
 	const argumentsTypes = [
@@ -344,6 +345,7 @@ export interface LiquidateQuoteOptions {
 		  ];
 	typeArguments: [string, string];
 }
+/** Twin: `liquidate_quote_upgraded`. Edit both. */
 export function liquidateQuote(options: LiquidateQuoteOptions) {
 	const packageAddress = options.package ?? '@deepbook/margin-liquidation';
 	const argumentsTypes = [
@@ -399,3 +401,143 @@ export function balance(options: BalanceOptions) {
 			typeArguments: options.typeArguments,
 		});
 }
+export interface LiquidateBaseUpgradedArguments {
+	self: RawTransactionArgument<string>;
+	marginManager: RawTransactionArgument<string>;
+	registry: RawTransactionArgument<string>;
+	baseOracle: RawTransactionArgument<string>;
+	quoteOracle: RawTransactionArgument<string>;
+	baseMarginPool: RawTransactionArgument<string>;
+	quoteMarginPool: RawTransactionArgument<string>;
+	pool: RawTransactionArgument<string>;
+	repayAmount: RawTransactionArgument<number | bigint | null>;
+}
+export interface LiquidateBaseUpgradedOptions {
+	package?: string;
+	arguments:
+		| LiquidateBaseUpgradedArguments
+		| [
+				self: RawTransactionArgument<string>,
+				marginManager: RawTransactionArgument<string>,
+				registry: RawTransactionArgument<string>,
+				baseOracle: RawTransactionArgument<string>,
+				quoteOracle: RawTransactionArgument<string>,
+				baseMarginPool: RawTransactionArgument<string>,
+				quoteMarginPool: RawTransactionArgument<string>,
+				pool: RawTransactionArgument<string>,
+				repayAmount: RawTransactionArgument<number | bigint | null>,
+		  ];
+	typeArguments: [string, string];
+}
+/**
+ * `liquidate_base` against Pyth's upgraded Core.
+ *
+ * Pyth is replacing Core with a separately published package, so its
+ * `PriceInfoObject` is a distinct Move type and `liquidate_base`'s frozen
+ * signature can never accept it. Once Pyth stops publishing legacy Core the legacy
+ * entry aborts on staleness by itself, and this becomes the only way the vault can
+ * liquidate. The gate (`should_liquidate`) and the settlement
+ * (`settle_base_liquidation`) are shared with the legacy entry; the body between
+ * them is duplicated, because the two `PriceInfoObject` types cannot be unified.
+ * Twin: `liquidate_base`. Edit both.
+ */
+export function liquidateBaseUpgraded(options: LiquidateBaseUpgradedOptions) {
+	const packageAddress = options.package ?? '@deepbook/margin-liquidation';
+	const argumentsTypes = [
+		null,
+		null,
+		null,
+		null,
+		null,
+		null,
+		null,
+		null,
+		'0x1::option::Option<u64>',
+		'0x2::clock::Clock',
+	] satisfies (string | null)[];
+	const parameterNames = [
+		'self',
+		'marginManager',
+		'registry',
+		'baseOracle',
+		'quoteOracle',
+		'baseMarginPool',
+		'quoteMarginPool',
+		'pool',
+		'repayAmount',
+	];
+	return (tx: Transaction) =>
+		tx.moveCall({
+			package: packageAddress,
+			module: 'liquidation_vault',
+			function: 'liquidate_base_upgraded',
+			arguments: normalizeMoveArguments(options.arguments, argumentsTypes, parameterNames),
+			typeArguments: options.typeArguments,
+		});
+}
+export interface LiquidateQuoteUpgradedArguments {
+	self: RawTransactionArgument<string>;
+	marginManager: RawTransactionArgument<string>;
+	registry: RawTransactionArgument<string>;
+	baseOracle: RawTransactionArgument<string>;
+	quoteOracle: RawTransactionArgument<string>;
+	baseMarginPool: RawTransactionArgument<string>;
+	quoteMarginPool: RawTransactionArgument<string>;
+	pool: RawTransactionArgument<string>;
+	repayAmount: RawTransactionArgument<number | bigint | null>;
+}
+export interface LiquidateQuoteUpgradedOptions {
+	package?: string;
+	arguments:
+		| LiquidateQuoteUpgradedArguments
+		| [
+				self: RawTransactionArgument<string>,
+				marginManager: RawTransactionArgument<string>,
+				registry: RawTransactionArgument<string>,
+				baseOracle: RawTransactionArgument<string>,
+				quoteOracle: RawTransactionArgument<string>,
+				baseMarginPool: RawTransactionArgument<string>,
+				quoteMarginPool: RawTransactionArgument<string>,
+				pool: RawTransactionArgument<string>,
+				repayAmount: RawTransactionArgument<number | bigint | null>,
+		  ];
+	typeArguments: [string, string];
+}
+/**
+ * `liquidate_quote` against Pyth's upgraded Core. See `liquidate_base_upgraded`.
+ * Twin: `liquidate_quote`. Edit both.
+ */
+export function liquidateQuoteUpgraded(options: LiquidateQuoteUpgradedOptions) {
+	const packageAddress = options.package ?? '@deepbook/margin-liquidation';
+	const argumentsTypes = [
+		null,
+		null,
+		null,
+		null,
+		null,
+		null,
+		null,
+		null,
+		'0x1::option::Option<u64>',
+		'0x2::clock::Clock',
+	] satisfies (string | null)[];
+	const parameterNames = [
+		'self',
+		'marginManager',
+		'registry',
+		'baseOracle',
+		'quoteOracle',
+		'baseMarginPool',
+		'quoteMarginPool',
+		'pool',
+		'repayAmount',
+	];
+	return (tx: Transaction) =>
+		tx.moveCall({
+			package: packageAddress,
+			module: 'liquidation_vault',
+			function: 'liquidate_quote_upgraded',
+			arguments: normalizeMoveArguments(options.arguments, argumentsTypes, parameterNames),
+			typeArguments: options.typeArguments,
+		});
+}

package/src/index.ts

@@ -23,6 +23,7 @@ export { MarginTPSLContract } from './transactions/marginTPSL.js';
 
 // Pyth price feed integration
 export { SuiPythClient, SuiPriceServiceConnection } from './pyth/pyth.js';
+export type { PriceServiceConnectionConfig } from './pyth/PriceServiceConnection.js';
 
 // BCS types for parsing on-chain data
 export { Account, Balances, Order, OrderDeepPrice, VecSet } from './types/bcs.js';
@@ -34,6 +35,7 @@ export type {
 	Pool,
 	MarginManager,
 	MarginPool,
+	PythConfig,
 	Config,
 } from './types/index.js';
 
@@ -106,6 +108,8 @@ export {
 	testnetPackageIds,
 	mainnetPythConfigs,
 	testnetPythConfigs,
+	PYTH_UPGRADED_HERMES,
+	DEEPBOOK_HERMES_PROXY,
 } from './utils/constants.js';
 export {
 	DEEP_SCALAR,

package/src/pyth/PriceServiceConnection.ts

@@ -12,6 +12,15 @@ export type PriceFeedRequestConfig = {
 export type PriceServiceConnectionConfig = {
 	timeout?: number;
 	httpRetries?: number;
+	/**
+	 * Bearer token for Hermes deployments that authenticate. The endpoint serving Pyth's
+	 * upgraded Core answers 401 without one.
+	 *
+	 * `accessToken` is chosen to converge with the in-flight `@mysten/suins` Pyth migration
+	 * (ts-sdks#1158), which takes the same credential under this name. That is not yet
+	 * published, so this is a convergence target rather than an existing convention.
+	 */
+	accessToken?: string;
 };
 export class PriceServiceConnection {
 	private httpClient: AxiosInstance;
@@ -25,6 +34,7 @@ export class PriceServiceConnection {
 		this.httpClient = axios.create({
 			baseURL: endpoint,
 			timeout: config?.timeout || 5000,
+			headers: config?.accessToken ? { Authorization: `Bearer ${config.accessToken}` } : undefined,
 		});
 		axiosRetry(this.httpClient, {
 			retries: config?.httpRetries || 3,
@@ -32,17 +42,68 @@ export class PriceServiceConnection {
 		});
 	}
 	/**
-	 * Fetch latest VAAs of given price IDs.
+	 * Fetch the latest price update data for the given price IDs.
+	 *
+	 * Uses Hermes v2 (`/v2/updates/price/latest`). The v1 endpoint (`/api/latest_vaas`)
+	 * is deprecated; it returned the same payload this reads out of `binary.data`.
+	 *
+	 * Hermes returns one accumulator message covering every requested feed, not one per
+	 * feed, so the result is normally a single element regardless of `priceIds.length`.
 	 *
 	 * @param priceIds Array of hex-encoded price IDs.
-	 * @returns Array of base64 encoded VAAs.
+	 * @returns Array of base64-encoded update messages.
 	 */
 	async getLatestVaas(priceIds: HexString[]): Promise<string[]> {
-		const response = await this.httpClient.get('/api/latest_vaas', {
-			params: {
-				ids: priceIds,
-			},
-		});
-		return response.data;
+		let response;
+		try {
+			response = await this.httpClient.get('/v2/updates/price/latest', {
+				params: {
+					// Serialized explicitly rather than relying on axios's array encoding, which is
+					// what Hermes expects and what a future axios major could change under us.
+					'ids[]': priceIds,
+					encoding: 'base64',
+					parsed: false,
+				},
+			});
+		} catch (error) {
+			// An axios error carries `config.headers` — including `Authorization` — and both
+			// `JSON.stringify(err)` and `err.toJSON()` serialize it. Callers log failed requests,
+			// so letting the raw error escape would put the bearer token in their logs. Re-throw
+			// a plain error carrying only what is useful for diagnosis.
+			throw new Error(`Hermes request failed: ${describeRequestError(error)}`, {
+				cause: undefined,
+			});
+		}
+
+		const data = response.data?.binary?.data;
+		if (!Array.isArray(data)) {
+			throw new Error(
+				`Unexpected Hermes response: expected 'binary.data' array from /v2/updates/price/latest, got ${JSON.stringify(
+					response.data,
+				)?.slice(0, 200)}`,
+			);
+		}
+
+		return data;
+	}
+}
+
+/**
+ * A diagnosable one-line summary of a failed request that cannot contain the access token:
+ * status and response body only, never the request config or its headers.
+ */
+function describeRequestError(error: unknown): string {
+	const e = error as {
+		response?: { status?: number; statusText?: string; data?: unknown };
+		code?: string;
+		message?: string;
+	};
+	if (e?.response) {
+		const body =
+			typeof e.response.data === 'string' ? e.response.data : JSON.stringify(e.response.data);
+		return `${e.response.status ?? '?'} ${e.response.statusText ?? ''} ${body?.slice(0, 200) ?? ''}`.trim();
 	}
+	// No response: a transport failure. `message` is a fixed axios string ("timeout of 5000ms
+	// exceeded", "Network Error") that embeds no header material.
+	return e?.code ? `${e.code} ${e.message ?? ''}`.trim() : (e?.message ?? 'unknown error');
 }

package/src/queries/priceFeedQueries.ts

@@ -6,6 +6,8 @@ import type { Transaction } from '@mysten/sui/transactions';
 import { PriceInfoObject } from '../contracts/pyth/price_info.js';
 import { SuiPriceServiceConnection, SuiPythClient } from '../pyth/pyth.js';
 import { PRICE_INFO_OBJECT_MAX_AGE_MS } from '../utils/config.js';
+import { DEEPBOOK_HERMES_PROXY, PYTH_UPGRADED_HERMES } from '../utils/constants.js';
+import { ConfigurationError } from '../utils/errors.js';
 import type { QueryContext } from './context.js';
 
 export class PriceFeedQueries {
@@ -15,6 +17,53 @@ export class PriceFeedQueries {
 		this.#ctx = ctx;
 	}
 
+	/**
+	 * The Hermes endpoint serving the Pyth deployment margin is configured against.
+	 *
+	 * There are two routes, chosen by whether the caller brought
+	 * credentials. With `accessToken` set, the SDK talks to Pyth directly and no DeepBook
+	 * infrastructure is in the path — the token is sent to Pyth's own host, so a token
+	 * minted for some other endpoint must be paired with an explicit `hermesEndpoint`.
+	 *
+	 * Note the converse too: an explicit `hermesEndpoint` wins over everything, and the
+	 * token is sent to whatever host it names. Point it at a mirror or staging proxy while
+	 * a production token is still configured and the credential goes there.
+	 *
+	 * Without a token it falls back to the DeepBook-operated proxy, which supplies
+	 * credentials server-side; that proxy is not deployed yet, so today this path throws a
+	 * `ConfigurationError` instead. An explicit `hermesEndpoint` overrides both.
+	 */
+	#hermesEndpoint(): string {
+		const { hermesEndpoint, accessToken } = this.#ctx.config.pyth;
+		if (hermesEndpoint) {
+			return hermesEndpoint;
+		}
+
+		if (accessToken) {
+			return PYTH_UPGRADED_HERMES;
+		}
+		if (DEEPBOOK_HERMES_PROXY) {
+			return DEEPBOOK_HERMES_PROXY;
+		}
+
+		throw new ConfigurationError(
+			"Pushing price updates against Pyth's upgraded Core needs credentials: its Hermes answers 401 unauthenticated. Set the client's `pythAccessToken` option (or `pyth.accessToken`), or point `pyth.hermesEndpoint` at an endpoint that supplies credentials itself.",
+		);
+	}
+
+	/**
+	 * A Hermes connection for the active Pyth deployment, carrying any configured auth
+	 * headers. The endpoint serving the upgraded Core requires an `Authorization` header
+	 * and answers 401 without one.
+	 */
+	#connection(): SuiPriceServiceConnection {
+		const { accessToken } = this.#ctx.config.pyth;
+		return new SuiPriceServiceConnection(
+			this.#hermesEndpoint(),
+			accessToken ? { accessToken } : undefined,
+		);
+	}
+
 	async getPriceInfoObject(tx: Transaction, coinKey: string): Promise<string> {
 		this.#ctx.config.requirePyth();
 		const currentTime = Date.now();
@@ -23,21 +72,16 @@ export class PriceFeedQueries {
 			priceInfoObjectAge &&
 			currentTime - priceInfoObjectAge * 1000 < PRICE_INFO_OBJECT_MAX_AGE_MS
 		) {
-			return await this.#ctx.config.getCoin(coinKey).priceInfoObjectId!;
+			return this.#ctx.config.getPriceInfoObjectId(coinKey);
 		}
 
-		const endpoint =
-			this.#ctx.config.network === 'testnet'
-				? 'https://hermes-beta.pyth.network'
-				: 'https://hermes.pyth.network';
-		const connection = new SuiPriceServiceConnection(endpoint);
+		const connection = this.#connection();
 
-		const priceIDs = [this.#ctx.config.getCoin(coinKey).feed!];
+		const priceIDs = [this.#ctx.config.getFeedId(coinKey)];
 
 		const priceUpdateData = await connection.getPriceFeedsUpdateData(priceIDs);
 
-		const wormholeStateId = this.#ctx.config.pyth.wormholeStateId;
-		const pythStateId = this.#ctx.config.pyth.pythStateId;
+		const { pythStateId, wormholeStateId } = this.#ctx.config.pyth;
 
 		const client = new SuiPythClient(this.#ctx.client, pythStateId, wormholeStateId);
 
@@ -55,7 +99,7 @@ export class PriceFeedQueries {
 		const coinToObjectId: Record<string, string> = {};
 		const objectIds: string[] = [];
 		for (const coinKey of coinKeys) {
-			const priceInfoObjectId = this.#ctx.config.getCoin(coinKey).priceInfoObjectId!;
+			const priceInfoObjectId = this.#ctx.config.getPriceInfoObjectId(coinKey);
 			coinToObjectId[coinKey] = priceInfoObjectId;
 			objectIds.push(priceInfoObjectId);
 		}
@@ -92,38 +136,44 @@ export class PriceFeedQueries {
 			return result;
 		}
 
+		// Distinct coins can share a feed. No shipped map has a collision — every configured
+		// coin is on its own feed — but `coins` is a public constructor option, and coins
+		// tracking the same underlying (a wrapped asset priced off its reference, say) are
+		// the normal reason to supply one. Deduplicate before building the update:
+		// a feed listed twice would emit two `update_single_price_feed` calls against the same
+		// object off one hot-potato vector, and pay two update fees for it. One feed can also
+		// map to several coins, so the reverse index holds a list, not a single key.
 		const staleFeedIds: string[] = [];
-		const feedIdToCoinKey: Record<string, string> = {};
+		const feedIdToCoinKeys: Record<string, string[]> = {};
 		for (const coinKey of staleCoinKeys) {
-			const feedId = this.#ctx.config.getCoin(coinKey).feed!;
-			staleFeedIds.push(feedId);
-			feedIdToCoinKey[feedId] = coinKey;
+			const feedId = this.#ctx.config.getFeedId(coinKey);
+			if (!feedIdToCoinKeys[feedId]) {
+				feedIdToCoinKeys[feedId] = [];
+				staleFeedIds.push(feedId);
+			}
+			feedIdToCoinKeys[feedId].push(coinKey);
 		}
 
-		const endpoint =
-			this.#ctx.config.network === 'testnet'
-				? 'https://hermes-beta.pyth.network'
-				: 'https://hermes.pyth.network';
-		const connection = new SuiPriceServiceConnection(endpoint);
+		const connection = this.#connection();
 
 		const priceUpdateData = await connection.getPriceFeedsUpdateData(staleFeedIds);
 
-		const wormholeStateId = this.#ctx.config.pyth.wormholeStateId;
-		const pythStateId = this.#ctx.config.pyth.pythStateId;
+		const { pythStateId, wormholeStateId } = this.#ctx.config.pyth;
 		const pythClient = new SuiPythClient(this.#ctx.client, pythStateId, wormholeStateId);
 
 		const updatedObjectIds = await pythClient.updatePriceFeeds(tx, priceUpdateData, staleFeedIds);
 
 		for (let i = 0; i < staleFeedIds.length; i++) {
-			const coinKey = feedIdToCoinKey[staleFeedIds[i]];
-			result[coinKey] = updatedObjectIds[i];
+			for (const coinKey of feedIdToCoinKeys[staleFeedIds[i]]) {
+				result[coinKey] = updatedObjectIds[i];
+			}
 		}
 
 		return result;
 	}
 
 	async getPriceInfoObjectAge(coinKey: string): Promise<number> {
-		const priceInfoObjectId = this.#ctx.config.getCoin(coinKey).priceInfoObjectId!;
+		const priceInfoObjectId = this.#ctx.config.getPriceInfoObjectId(coinKey);
 		const res = await this.#ctx.client.core.getObject({
 			objectId: priceInfoObjectId,
 			include: {

package/src/transactions/marginAdmin.ts

@@ -412,11 +412,9 @@ export class MarginAdminContract {
 	newCoinTypeData =
 		(coinKey: string, maxConfBps: number, maxEwmaDifferenceBps: number) => (tx: Transaction) => {
 			const coin = this.#config.getCoin(coinKey);
-			if (!coin.feed) {
-				throw new Error('Coin feed not found');
-			}
+			const feed = this.#config.getFeedId(coinKey);
 			const priceFeedInput = new Uint8Array(
-				hexToBytes(coin['feed']!.startsWith('0x') ? coin.feed!.slice(2) : coin['feed']),
+				hexToBytes(feed.startsWith('0x') ? feed.slice(2) : feed),
 			);
 			return tx.add(
 				oracleMoveCalls.newCoinTypeDataFromCurrency({

package/src/transactions/marginLiquidations.ts

@@ -20,6 +20,20 @@ export class MarginLiquidationsContract {
 		this.#config = config;
 	}
 
+	/**
+	 * The oracle-taking liquidation entrypoints. Unlike the margin package,
+	 * `margin_liquidation` puts the upgraded entries in the same module as parallel
+	 * functions rather than in a parallel module, so these name a function rather than a
+	 * namespace. The vault's own deposit/withdraw/balance take no oracle and are unchanged.
+	 */
+	get #liquidateBaseCall() {
+		return liquidationVaultMoveCalls.liquidateBaseUpgraded;
+	}
+
+	get #liquidateQuoteCall() {
+		return liquidationVaultMoveCalls.liquidateQuoteUpgraded;
+	}
+
 	/**
 	 * @description Create a new liquidation vault
 	 * @param {string} liquidationAdminCap The liquidation admin cap object ID
@@ -109,14 +123,14 @@ export class MarginLiquidationsContract {
 					: tx.pure.option('u64', null);
 
 			tx.add(
-				liquidationVaultMoveCalls.liquidateBase({
+				this.#liquidateBaseCall({
 					package: this.#config.LIQUIDATION_PACKAGE_ID,
 					arguments: {
 						self: vaultId,
 						marginManager: managerAddress,
 						registry: this.#config.MARGIN_REGISTRY_ID,
-						baseOracle: baseCoin.priceInfoObjectId!,
-						quoteOracle: quoteCoin.priceInfoObjectId!,
+						baseOracle: this.#config.getPriceInfoObjectId(pool.baseCoin),
+						quoteOracle: this.#config.getPriceInfoObjectId(pool.quoteCoin),
 						baseMarginPool: baseMarginPool.address,
 						quoteMarginPool: quoteMarginPool.address,
 						pool: pool.address,
@@ -152,14 +166,14 @@ export class MarginLiquidationsContract {
 					: tx.pure.option('u64', null);
 
 			tx.add(
-				liquidationVaultMoveCalls.liquidateQuote({
+				this.#liquidateQuoteCall({
 					package: this.#config.LIQUIDATION_PACKAGE_ID,
 					arguments: {
 						self: vaultId,
 						marginManager: managerAddress,
 						registry: this.#config.MARGIN_REGISTRY_ID,
-						baseOracle: baseCoin.priceInfoObjectId!,
-						quoteOracle: quoteCoin.priceInfoObjectId!,
+						baseOracle: this.#config.getPriceInfoObjectId(pool.baseCoin),
+						quoteOracle: this.#config.getPriceInfoObjectId(pool.quoteCoin),
 						baseMarginPool: baseMarginPool.address,
 						quoteMarginPool: quoteMarginPool.address,
 						pool: pool.address,