@0xmonaco/core 0.8.5 → 0.8.7-develop.0f12336

package/README.md

@@ -62,26 +62,17 @@ npm install viem@^2.31.7
 
 ## Network Support
 
-The SDK supports the following preset networks. Configure the network by providing the `network` and `seiRpcUrl` parameters:
+The SDK supports the following documented preset networks. Configure the network by providing the `network` and `seiRpcUrl` parameters:
 
 **Preset Networks:**
-- `"development"` - Development environment (https://develop.apimonaco.xyz)
 - `"staging"` - Staging environment (https://staging.apimonaco.xyz)
 - `"mainnet"` - Production environment (https://api.monaco.xyz)
-- `"local"` - Local development (http://localhost:8080)
 
 WebSocket URLs are automatically resolved per network.
 
 ```typescript
 import { MonacoSDK } from "@0xmonaco/core";
 
-// Development configuration
-const devSdk = new MonacoSDK({
-  walletClient,
-  network: "development",
-  seiRpcUrl: "https://evm-rpc-testnet.sei-apis.com",
-});
-
 // Staging configuration
 const stagingSdk = new MonacoSDK({
   walletClient,
@@ -114,7 +105,7 @@ const walletClient = createWalletClient({
 
 const monaco = new MonacoSDK({
   walletClient,
-  network: "development", // or "staging", "mainnet", "local"
+  network: "staging", // or "mainnet"
   seiRpcUrl: "https://evm-rpc-testnet.sei-apis.com", // or https://evm-rpc.sei-apis.com for mainnet
 });
 
@@ -251,7 +242,7 @@ interface SDKConfig {
   /** Wallet client for signing operations (optional - can be set later via setWalletClient) */
   walletClient?: WalletClient;
   
-  /** Network preset: "local", "development", "staging", or "mainnet" */
+  /** Use "staging" for public testnet or "mainnet" for production. */
   network: Network;
   
   /** RPC URL for Sei blockchain interactions */

package/dist/api/applications/api.d.ts

@@ -1,23 +1,25 @@
 /**
  * Applications API Implementation
  *
- * Handles application configuration operations. All operations go through
- * the API Gateway and require valid authentication.
- *
- * This class provides an interface for retrieving application configuration
- * on the Monaco protocol.
+ * Handles application configuration and reporting operations. This is a
+ * mixed-auth domain: `getApplicationConfig` is session-authenticated, while
+ * the reporting methods are backend-authenticated via the application secret
+ * key (set with {@link BaseAPI.setServerKey}, sent as `x-server-key`).
  *
  * @example
  * ```typescript
  * const applicationsAPI = new ApplicationsAPIImpl(apiUrl);
  *
- * // Get application configuration
+ * // Get application configuration (session auth)
  * const config = await applicationsAPI.getApplicationConfig();
  * console.log(`App name: ${config.name}`);
- * console.log(`Allowed origins: ${config.allowedOrigins.join(', ')}`);
+ *
+ * // Reporting endpoints (backend auth)
+ * applicationsAPI.setServerKey("sk_live_...");
+ * const orders = await applicationsAPI.listApplicationOrders({ status: "FILLED" });
  * ```
  */
-import type { ApplicationConfigResponse, ApplicationsAPI } from "@0xmonaco/types";
+import type { ApplicationConfigResponse, ApplicationsAPI, GetAppStatsParams, GetAppStatsResponse, ListAppBalancesParams, ListAppBalancesResponse, ListAppMovementsParams, ListAppMovementsResponse, ListAppOrdersParams, ListAppOrdersResponse, ListAppUsersParams, ListAppUsersResponse } from "@0xmonaco/types";
 import { BaseAPI } from "../base";
 export declare class ApplicationsAPIImpl extends BaseAPI implements ApplicationsAPI {
     /**
@@ -40,4 +42,55 @@ export declare class ApplicationsAPIImpl extends BaseAPI implements Applications
      * ```
      */
     getApplicationConfig(): Promise<ApplicationConfigResponse>;
+    /**
+     * Lists orders placed by the application's users.
+     *
+     * Backend-authenticated — call {@link BaseAPI.setServerKey} first.
+     *
+     * @param params - Pagination and filter options
+     * @returns Promise resolving to a paginated list of orders
+     * @throws {APIError} When the server key is unset or the request fails
+     */
+    listApplicationOrders(params?: ListAppOrdersParams): Promise<ListAppOrdersResponse>;
+    /**
+     * Lists the application's users.
+     *
+     * Backend-authenticated — call {@link BaseAPI.setServerKey} first.
+     *
+     * @param params - Pagination and filter options
+     * @returns Promise resolving to a paginated list of users
+     * @throws {APIError} When the server key is unset or the request fails
+     */
+    listApplicationUsers(params?: ListAppUsersParams): Promise<ListAppUsersResponse>;
+    /**
+     * Lists ledger movements for the application's users.
+     *
+     * Backend-authenticated — call {@link BaseAPI.setServerKey} first.
+     *
+     * @param params - Pagination and filter options
+     * @returns Promise resolving to a paginated list of movements
+     * @throws {APIError} When the server key is unset or the request fails
+     */
+    listApplicationMovements(params?: ListAppMovementsParams): Promise<ListAppMovementsResponse>;
+    /**
+     * Lists user balances held within the application.
+     *
+     * Backend-authenticated — call {@link BaseAPI.setServerKey} first.
+     *
+     * @param params - Pagination and filter options
+     * @returns Promise resolving to a paginated list of balances
+     * @throws {APIError} When the server key is unset or the request fails
+     */
+    listApplicationBalances(params?: ListAppBalancesParams): Promise<ListAppBalancesResponse>;
+    /**
+     * Gets aggregate volume and fee stats for the application.
+     *
+     * Stats are scoped to trades where the application's users were the taker.
+     * Backend-authenticated — call {@link BaseAPI.setServerKey} first.
+     *
+     * @param params - Optional `since` filter
+     * @returns Promise resolving to the application stats
+     * @throws {APIError} When the server key is unset or the request fails
+     */
+    getApplicationStats(params?: GetAppStatsParams): Promise<GetAppStatsResponse>;
 }

package/dist/api/applications/api.js

@@ -1,23 +1,26 @@
 /**
  * Applications API Implementation
  *
- * Handles application configuration operations. All operations go through
- * the API Gateway and require valid authentication.
- *
- * This class provides an interface for retrieving application configuration
- * on the Monaco protocol.
+ * Handles application configuration and reporting operations. This is a
+ * mixed-auth domain: `getApplicationConfig` is session-authenticated, while
+ * the reporting methods are backend-authenticated via the application secret
+ * key (set with {@link BaseAPI.setServerKey}, sent as `x-server-key`).
  *
  * @example
  * ```typescript
  * const applicationsAPI = new ApplicationsAPIImpl(apiUrl);
  *
- * // Get application configuration
+ * // Get application configuration (session auth)
  * const config = await applicationsAPI.getApplicationConfig();
  * console.log(`App name: ${config.name}`);
- * console.log(`Allowed origins: ${config.allowedOrigins.join(', ')}`);
+ *
+ * // Reporting endpoints (backend auth)
+ * applicationsAPI.setServerKey("sk_live_...");
+ * const orders = await applicationsAPI.listApplicationOrders({ status: "FILLED" });
  * ```
  */
 import { BaseAPI } from "../base";
+import { perpRoutes } from "../perp/routes";
 export class ApplicationsAPIImpl extends BaseAPI {
     /**
      * Gets the configuration for the authenticated application.
@@ -45,10 +48,71 @@ export class ApplicationsAPIImpl extends BaseAPI {
         return {
             id: data.id,
             name: data.name,
-            allowedOrigins: data.allowed_origins,
-            webhookUrl: data.webhook_url,
-            vaultContractAddress: data.vault_contract_address,
-            clientId: data.client_id,
+            allowedOrigins: data.allowedOrigins,
+            webhookUrl: data.webhookUrl,
+            vaultContractAddress: data.vaultContractAddress,
+            clientId: data.clientId,
         };
     }
+    /**
+     * Lists orders placed by the application's users.
+     *
+     * Backend-authenticated — call {@link BaseAPI.setServerKey} first.
+     *
+     * @param params - Pagination and filter options
+     * @returns Promise resolving to a paginated list of orders
+     * @throws {APIError} When the server key is unset or the request fails
+     */
+    async listApplicationOrders(params) {
+        return await this.makeBackendRequest(perpRoutes.applications.orders(params));
+    }
+    /**
+     * Lists the application's users.
+     *
+     * Backend-authenticated — call {@link BaseAPI.setServerKey} first.
+     *
+     * @param params - Pagination and filter options
+     * @returns Promise resolving to a paginated list of users
+     * @throws {APIError} When the server key is unset or the request fails
+     */
+    async listApplicationUsers(params) {
+        return await this.makeBackendRequest(perpRoutes.applications.users(params));
+    }
+    /**
+     * Lists ledger movements for the application's users.
+     *
+     * Backend-authenticated — call {@link BaseAPI.setServerKey} first.
+     *
+     * @param params - Pagination and filter options
+     * @returns Promise resolving to a paginated list of movements
+     * @throws {APIError} When the server key is unset or the request fails
+     */
+    async listApplicationMovements(params) {
+        return await this.makeBackendRequest(perpRoutes.applications.movements(params));
+    }
+    /**
+     * Lists user balances held within the application.
+     *
+     * Backend-authenticated — call {@link BaseAPI.setServerKey} first.
+     *
+     * @param params - Pagination and filter options
+     * @returns Promise resolving to a paginated list of balances
+     * @throws {APIError} When the server key is unset or the request fails
+     */
+    async listApplicationBalances(params) {
+        return await this.makeBackendRequest(perpRoutes.applications.balances(params));
+    }
+    /**
+     * Gets aggregate volume and fee stats for the application.
+     *
+     * Stats are scoped to trades where the application's users were the taker.
+     * Backend-authenticated — call {@link BaseAPI.setServerKey} first.
+     *
+     * @param params - Optional `since` filter
+     * @returns Promise resolving to the application stats
+     * @throws {APIError} When the server key is unset or the request fails
+     */
+    async getApplicationStats(params) {
+        return await this.makeBackendRequest(perpRoutes.applications.stats(params));
+    }
 }

package/dist/api/auth/api.d.ts

@@ -1,11 +1,13 @@
 /**
  * Auth API Implementation
  *
- * Handles authentication operations including challenge creation, signature verification,
- * and backend authentication. All operations go through the API Gateway.
+ * Handles wallet authentication operations including challenge creation, signature
+ * verification, and session lifecycle. All operations go through the API Gateway.
  *
- * This class provides a complete interface for authentication on the Monaco protocol,
- * including frontend wallet authentication and backend service authentication.
+ * This class provides a complete interface for wallet-based authentication on the
+ * Monaco protocol. Backend services authenticate separately by setting their
+ * application secret key (`sk_...`) via {@link BaseAPI.setServerKey}, which is sent
+ * in the `x-server-key` header on backend requests — there is no token exchange.
  *
  * @example
  * ```typescript
@@ -23,12 +25,9 @@
  *   challenge.nonce,
  *   clientId
  * );
- *
- * // Authenticate backend service
- * const backendAuth = await authAPI.authenticateBackend(secretKey);
  * ```
  */
-import type { AuthAPI, AuthState, BackendAuthResponse, ChallengeResponse, TokenRefreshResponse } from "@0xmonaco/types";
+import type { AuthAPI, AuthState, ChallengeResponse, SessionCredentials, SessionRefreshResponse } from "@0xmonaco/types";
 import type { Chain, WalletClient } from "viem";
 import { BaseAPI } from "../base";
 export declare class AuthAPIImpl extends BaseAPI implements AuthAPI {
@@ -51,20 +50,24 @@ export declare class AuthAPIImpl extends BaseAPI implements AuthAPI {
      * Complete authentication flow for frontend applications.
      *
      * This method handles the entire authentication process:
-     * 1. Creates a challenge
-     * 2. Signs the challenge message
-     * 3. Verifies the signature and returns JWT tokens
+     * 1. Generates a fresh ed25519 session keypair locally
+     * 2. Creates a challenge that commits to the session public key
+     * 3. Signs the challenge message with the wallet
+     * 4. Verifies the signature, registering the session public key
+     *
+     * The returned {@link AuthState} carries the session keypair; sign subsequent
+     * requests with the private key (the wallet is not used again until the
+     * session expires).
      *
      * @param clientId - Client ID of the application
-     * @returns Promise resolving to the verification response with JWT tokens
+     * @returns Promise resolving to the authentication state (with the session keypair)
      * @throws {APIError} When authentication fails
      * @throws {InvalidConfigError} When wallet account is not available
      *
      * @example
      * ```typescript
-     * // Complete authentication in one call
      * const authResult = await authAPI.authenticate("my-app-client-id");
-     * console.log(`Access token: ${authResult.access_token}`);
+     * console.log(`Session public key: ${authResult.sessionPublicKey}`);
      * console.log(`User ID: ${authResult.user.id}`);
      * ```
      */
@@ -109,7 +112,7 @@ export declare class AuthAPIImpl extends BaseAPI implements AuthAPI {
      * console.log(`Nonce: ${challenge.nonce}`);
      * ```
      */
-    createChallenge(address: string, clientId: string): Promise<ChallengeResponse>;
+    createChallenge(address: string, clientId: string, sessionPublicKey: string): Promise<ChallengeResponse>;
     /**
      * Verifies a signature for frontend authentication.
      *
@@ -117,90 +120,55 @@ export declare class AuthAPIImpl extends BaseAPI implements AuthAPI {
      * authenticated API access. This is the second step in the authentication flow.
      *
      * @param address - Wallet address of the user
-     * @param signature - Signature of the challenge message
+     * @param signature - Wallet signature of the challenge message
      * @param nonce - Nonce from the challenge response
      * @param clientId - Client ID of the application
-     * @returns Promise resolving to the verification response with JWT tokens
+     * @param session - The locally-generated session keypair (hex-encoded)
+     * @returns Promise resolving to the authentication state (with the session keypair)
      * @throws {APIError} When signature verification fails
      *
      * @example
      * ```typescript
-     * // First create a challenge
-     * const challenge = await authAPI.createChallenge(address, clientId);
-     *
-     * // User signs the challenge message with their wallet
+     * const keypair = generateSessionKeypair();
+     * const session = { publicKey: publicKeyHex(keypair), privateKey: privateKeyHex(keypair) };
+     * const challenge = await authAPI.createChallenge(address, clientId, session.publicKey);
      * const signature = await wallet.signMessage(challenge.message);
-     *
-     * // Verify the signature and get tokens
-     * const authResult = await authAPI.verifySignature(
-     *   address,
-     *   signature,
-     *   challenge.nonce,
-     *   clientId
-     * );
-     *
-     * console.log(`Access token: ${authResult.accessToken}`);
-     * console.log(`User ID: ${authResult.user.id}`);
+     * const authResult = await authAPI.verifySignature(address, signature, challenge.nonce, clientId, session);
+     * console.log(`Session public key: ${authResult.sessionPublicKey}`);
      * ```
      */
-    verifySignature(address: string, signature: string, nonce: string, clientId: string): Promise<AuthState>;
+    verifySignature(address: string, signature: string, nonce: string, clientId: string, session: SessionCredentials): Promise<AuthState>;
     /**
-     * Authenticates a backend service using a secret key.
+     * Extends the current session's expiry.
      *
-     * Returns JWT tokens for API access. This method is used for backend services
-     * that need to authenticate with the Monaco API Gateway.
+     * The request is signed with the active session key (set via
+     * {@link setSessionKeypair}); the server bumps the session's `expiresAt`.
+     * No new credential is issued — the same keypair keeps working.
      *
-     * @param secretKey - Secret key of the application
-     * @returns Promise resolving to the backend auth response with JWT tokens
-     * @throws {APIError} When backend authentication fails
+     * @returns Promise resolving to the new expiry
+     * @throws {APIError} When refresh fails (e.g. session expired or revoked)
      *
      * @example
      * ```typescript
-     * const backendAuth = await authAPI.authenticateBackend("my-secret-key");
-     * console.log(`Backend access token: ${backendAuth.accessToken}`);
-     * console.log(`Application: ${backendAuth.application.name}`);
+     * const { expiresAt } = await authAPI.refreshSession();
+     * console.log(`Session now expires at: ${new Date(expiresAt * 1000)}`);
      * ```
      */
-    authenticateBackend(secretKey: string): Promise<BackendAuthResponse>;
+    refreshSession(): Promise<SessionRefreshResponse>;
     /**
-     * Refreshes an access token using a refresh token.
-     *
-     * Obtains a new access token using a valid refresh token. This is useful for
-     * maintaining long-term authentication without requiring the user to sign
-     * a new challenge.
-     *
-     * @param refreshToken - The refresh token to use
-     * @returns Promise resolving to new access and refresh tokens
-     * @throws {APIError} When token refresh fails
-     *
-     * @example
-     * ```typescript
-     * const newTokens = await authAPI.refreshToken(refreshToken);
-     * console.log(`New access token: ${newTokens.accessToken}`);
-     * console.log(`Expires at: ${new Date(newTokens.expiresAt * 1000)}`);
-     * ```
-     */
-    refreshToken(refreshToken: string): Promise<TokenRefreshResponse>;
-    /**
-     * Revokes the current session's refresh token.
-     *
-     * Invalidates the refresh token associated with the current access token,
-     * preventing it from being used to obtain new access tokens. This is useful
-     * for logout functionality or when a token has been compromised.
+     * Revokes the current session.
      *
-     * The server identifies the token to revoke from the access token in the
-     * Authorization header — no request body is needed.
+     * The request is signed with the active session key; the server deletes the
+     * matching session row. Used for logout or when a key may be compromised.
      *
-     * @returns Promise resolving when the token is revoked
-     * @throws {APIError} When token revocation fails
+     * @returns Promise resolving when the session is revoked
+     * @throws {APIError} When revocation fails
      *
      * @example
      * ```typescript
-     * // After authentication
-     * const authResult = await authAPI.authenticate(clientId);
-     * await authAPI.revokeToken();
-     * console.log("Token revoked successfully");
+     * await authAPI.revokeSession();
+     * console.log("Session revoked successfully");
      * ```
      */
-    revokeToken(): Promise<void>;
+    revokeSession(): Promise<void>;
 }