@0xmonaco/core 0.8.15 → 0.8.16

package/README.md

@@ -1,17 +1,6 @@
 # Monaco Core SDK
 
-⚠️ **EARLY DEVELOPMENT WARNING** ⚠️
-
-This package is currently in **early development**.
-
-**Breaking changes are expected** and may occur without notice. This version is intended for:
-- Early adopters and testing
-- Development and experimentation
-- Feedback collection
-
----
-
-Core SDK implementation for interacting with Monaco Protocol. This SDK provides a comprehensive implementation with Authentication, Vault, Trading, Market, and Profile APIs, featuring JWT authentication and secure API Gateway integration.
+Core SDK implementation for interacting with Monaco Protocol. This SDK provides a comprehensive implementation with Authentication, Vault, Trading, Market, and Profile APIs, featuring noncustodial session-key authentication and secure API Gateway integration.
 
 ## Installation
 
@@ -27,10 +16,10 @@ npm install viem@^2.31.7
 ## Features
 
 ### 🔐 **Authentication**
-- **JWT-based Authentication**: Secure token-based authentication
-- **Wallet Signature Verification**: EIP-712 signature-based login
-- **Token Refresh**: Automatic token refresh and management
-- **Session Management**: Secure session handling
+- **Session-key Authentication**: Noncustodial ed25519 session keys — the server never holds a credential that can impersonate you
+- **Wallet Signature Verification**: EIP-712 signature authorizes each session key
+- **Session Refresh**: Extend session expiry without re-prompting the wallet
+- **Server-key Auth**: Optional `sk_...` application key for backend/service access
 
 ### 🏦 **Vault Operations**
 - **Token Approvals**: ERC20 token approvals for vault usage
@@ -55,8 +44,8 @@ npm install viem@^2.31.7
 - **Balance Tracking**: Cross-platform balance monitoring
 
 ### 🔐 **Security Features**
-- **JWT Authentication**: Secure API access with token validation
-- **EIP-712 Signatures**: Type-safe, structured data signing for authentication
+- **Session-key Signing**: Every authenticated request is signed with a locally held ed25519 key
+- **EIP-712 Signatures**: Type-safe, structured data signing for session authorization
 - **API Gateway Integration**: Secure communication with Monaco backend
 - **TLS Encryption**: Secure API communications
 
@@ -114,9 +103,9 @@ async function authExample() {
   // Login with client ID and auto-connect authenticated WebSocket channels (Orders)
   const authState = await monaco.login("your-client-id", { connectWebSocket: true });
   console.log("Authenticated:", authState.user);
-  console.log("Tokens:", {
-    accessToken: authState.accessToken,
-    refreshToken: authState.refreshToken,
+  console.log("Session:", {
+    sessionPublicKey: authState.sessionPublicKey,
+    expiresAt: authState.expiresAt,
   });
   
   // Authenticated WebSocket channels are now connected - start receiving real-time updates
@@ -128,11 +117,11 @@ async function authExample() {
   // Check authentication status
   console.log("Is authenticated:", monaco.isAuthenticated());
   
-  // Logout (revokes the refresh token and disconnects authenticated WebSockets)
+  // Logout (revokes the session and disconnects authenticated WebSockets)
   await monaco.logout();
   
-  // Or manually revoke the token
-  await monaco.auth.revokeToken();
+  // Or manually revoke the session
+  await monaco.auth.revokeSession();
 }
 
 // Market Data
@@ -250,9 +239,9 @@ interface SDKConfig {
 }
 ```
 
-### Authentication & Token Management
+### Authentication & Session Management
 
-The SDK uses JWT tokens for authentication. Understanding the token structure is important:
+The SDK uses a noncustodial session-key scheme. On login it generates an ed25519 keypair locally, has your wallet authorize it via an EIP-712 signature, and signs every subsequent request with the private key — the server never holds a credential that can impersonate you.
 
 ```typescript
 // After login, you receive an AuthState object
@@ -260,35 +249,40 @@ const authState = await sdk.login(clientId);
 
 // AuthState structure:
 interface AuthState {
-  accessToken: string;    // For making authenticated API requests
-  refreshToken: string;   // For refreshing tokens AND revoking (logout)
-  expiresAt: number;      // When the access token expires
-  user: User;             // User information
+  sessionPublicKey: string;   // ed25519 public key registered with the server
+  sessionPrivateKey: string;  // ed25519 private key used to sign requests (the long-lived credential)
+  expiresAt: number;          // Unix timestamp (seconds) when the session expires
+  user: User;                 // User information
 }
 ```
 
+> The private key is the long-lived credential. Persist it (e.g. `localStorage`, same risk profile as a JWT) to survive page reloads without re-prompting the wallet. When the session expires, call `refreshAuth()` or re-`login()`.
+
 ```typescript
-// Revoke the current session's token
-await sdk.auth.revokeToken();
+// Revoke the current session
+await sdk.auth.revokeSession();
 
 // 💡 TIP: Use the built-in logout method
-await sdk.logout(); // Automatically calls revokeToken internally
+await sdk.logout(); // Automatically calls revokeSession internally
 ```
 
-**Token Management Methods:**
-- `login(clientId, options?)` - Authenticate and get tokens
+**Session Management Methods:**
+- `login(clientId, options?)` - Authorize a session key and authenticate
   - `clientId`: Your application's client ID
   - `options.connectWebSocket`: (optional) Auto-connect WebSocket after login (default: `false`)
-  - Returns `AuthState` with access token, refresh token, expiration, and user info
-- `logout()` - Revoke token, disconnect WebSocket, and clear state
-  - Calls `auth.revokeToken()` internally
+  - Returns `AuthState` with the session keypair, expiration, and user info
+- `logout()` - Revoke the session, disconnect WebSocket, and clear state
+  - Calls `auth.revokeSession()` internally
   - Disconnects authenticated WebSocket channels
   - Clears local auth state
-- `refreshAuth()` - Refresh the access token using the stored refresh token
-- `isAuthenticated()` - Check if user is authenticated
-- `getAuthState()` - Get current auth state with tokens
+- `refreshAuth()` - Extend the current session's expiry
+- `isAuthenticated()` - Check if a session is active
+- `getAuthState()` - Get current auth state with the session keypair
 - `setAuthState(authState)` - Set auth state directly (useful for sharing across SDK instances)
 
+**Server-key Auth (backend/service access):**
+- `setServerKey(serverKey)` - Authenticate with an application secret key (`sk_...`) instead of, or alongside, a session. Useful for server-side integrations.
+
 ### Vault API
 
 The vault API provides secure token management operations:
@@ -391,7 +385,7 @@ monaco.websocket.orderbook.subscribeToOrderbookEvents("BTC/USDC", "SPOT", (event
 
 #### Authenticated WebSockets (Orders)
 
-Requires JWT authentication for personal order updates. You can either auto-connect during login or connect manually:
+Requires an authenticated session for personal order updates. You can either auto-connect during login or connect manually:
 
 **Option 1: Auto-connect (recommended for authenticated channels)**
 ```typescript
@@ -515,15 +509,15 @@ bun run lint --filter @0xmonaco/core
 
 ## Security Features
 
-### JWT Authentication
-- **Token-based security**: Secure JWT tokens for API access
-- **EIP-712 login**: Wallet signature-based authentication
-- **Automatic refresh**: Seamless token renewal
-- **Session management**: Secure session handling
+### Session-key Authentication
+- **Noncustodial**: ed25519 session keys are generated locally; the server never holds a credential that can impersonate you
+- **EIP-712 login**: Wallet signature authorizes each session key
+- **Session refresh**: Extend expiry without re-prompting the wallet
+- **Server-key auth**: Optional `sk_...` application key for backend/service access
 
 ### API Gateway Integration
 - **Secure communication**: TLS encryption for all API calls
-- **Token validation**: Backend validates all JWT tokens
+- **Request signing**: Backend verifies the session signature on every authenticated request
 - **Rate limiting**: Protection against abuse
 - **Audit logging**: Complete transaction history
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@0xmonaco/core",
-	"version": "0.8.15",
+	"version": "0.8.16",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -23,8 +23,8 @@
 		"viem": "^2.45.2"
 	},
 	"dependencies": {
-		"@0xmonaco/contracts": "0.8.15",
-		"@0xmonaco/types": "0.8.15",
+		"@0xmonaco/contracts": "0.8.16",
+		"@0xmonaco/types": "0.8.16",
 		"@noble/curves": "^1.9.1",
 		"@noble/hashes": "^1.8.0",
 		"http-status-codes": "^2.3.0"