@phantom/server-sdk 0.0.2 → 0.0.3

package/README.md

@@ -1,6 +1,6 @@
-# Server SDK
+# Phantom Server SDK
 
-This package provides integration with @phantom/openapi-wallet-service for secure wallet management and transaction signing.
+The Phantom Server SDK enables secure wallet creation, message signing and transaction signing and submission for your applications.
 
 ## Installation
 
@@ -10,19 +10,15 @@ npm install @phantom/server-sdk
 
 ## Configuration
 
-The SDK requires the following configuration:
-
-- `apiPrivateKey`: Your signing key for authentication (base58 encoded)
-- `organizationId`: Your organization ID from Phantom
-- `apiBaseUrl`: The wallet API endpoint URL
+To get started, initialize the SDK with your credentials:
 
 ```typescript
 import { ServerSDK } from '@phantom/server-sdk';
 
 const sdk = new ServerSDK({
-  apiPrivateKey: 'your-signing-key-base58',
-  organizationId: 'your-org-id',
-  apiBaseUrl: 'https://api.phantom.app/v1'
+  apiPrivateKey: 'your-private-key',  // Base58 encoded private key
+  organizationId: 'your-org-id',      // Your organization ID
+  apiBaseUrl: 'https://api.phantom.app/wallet'
 });
 ```
 
@@ -95,23 +91,24 @@ CAIP-2 identifiers follow the format: `namespace:reference`
 ## Methods
 
 ### createWallet(walletName?: string)
-Creates a new wallet with an optional name. If no name is provided, a default name with timestamp is used.
-After creation, it retrieves the public key by signing an empty payload.
+Creates a new wallet in your organization. Each wallet supports multiple chains.
 
 ```typescript
 const wallet = await sdk.createWallet('My Main Wallet');
 // Returns: { 
 //   walletId: 'wallet-uuid',
-//   addresses: [{ addressType: 'Solana', address: 'public-key' }]
+//   addresses: [
+//     { addressType: 'Solana', address: '...' },
+//     { addressType: 'Ethereum', address: '...' },
+//     { addressType: 'BitcoinSegwit', address: '...' },
+//     { addressType: 'Sui', address: '...' }
+//   ]
 // }
 ```
 
 ### signAndSendTransaction(walletId: string, transaction: Uint8Array, networkId: string)
-Signs a transaction using the wallet service. The transaction should be provided as a Uint8Array and will be encoded as base64 before sending to the KMS.
-
-The SDK automatically derives the submission configuration from the CAIP-2 network ID. If the network supports transaction submission, Phantom will submit the transaction to the blockchain after signing.
-
-**Note:** This method returns only the signed transaction data. To get the transaction hash/signature, you need to extract it from the signed transaction.
+Signs a transaction and tries to submits it to the blockchain. The SDK automatically handles network-specific requirements.
+If the networkId is not supported for sending, the transaction will only be signed.
 
 ```typescript
 import { NetworkId } from '@phantom/server-sdk';
@@ -120,11 +117,12 @@ const transactionBuffer = new Uint8Array([...]); // Your serialized transaction
 const result = await sdk.signAndSendTransaction(
   'wallet-id',
   transactionBuffer,
-  NetworkId.SOLANA_MAINNET // Using enum - submission config automatically derived
+  NetworkId.SOLANA_MAINNET
 );
 
 // Returns: { 
 //   rawTransaction: 'base64-signed-transaction'
+//   txHash: 'tx-hash-string'
 // }
 
 // Extract the transaction signature (hash)
@@ -136,17 +134,47 @@ const signature = signedTx.signature
 ```
 
 ### signMessage(walletId: string, message: string, networkId: string)
-Signs a message with the specified wallet using the signRawPayload method.
+Signs a message with the specified wallet.
 
 ```typescript
 const signature = await sdk.signMessage(
   'wallet-id', 
   'Hello World', 
-  NetworkId.SOLANA_MAINNET // Using enum for CAIP-2 network ID
+  NetworkId.SOLANA_MAINNET
 );
 // Returns: base64 encoded signature
 ```
 
+### getWallets(limit?: number, offset?: number)
+Retrieves all wallets for your organization with pagination support.
+
+```typescript
+// Get first 10 wallets
+const result = await sdk.getWallets(10, 0);
+// Returns: {
+//   wallets: [{ walletId: '...', walletName: '...' }, ...],
+//   totalCount: 25,
+//   limit: 10,
+//   offset: 0
+// }
+
+// Get all wallets (default limit: 20)
+const allWallets = await sdk.getWallets();
+```
+
+### getWalletAddresses(walletId: string, derivationPaths?: string[])
+Retrieves addresses for a specific wallet across different blockchains.
+
+```typescript
+const addresses = await sdk.getWalletAddresses('wallet-id');
+// Returns: [
+//   { addressType: 'Solana', address: '...' },
+//   { addressType: 'Ethereum', address: '...' },
+//   { addressType: 'Bitcoin', address: '...' },
+//   { addressType: 'Sui', address: '...' }
+// ]
+```
+
 ## CAIP-2 Utility Functions
 
 The SDK exports several utility functions for working with CAIP-2 network identifiers:
@@ -176,33 +204,25 @@ const solanaNetworks = getNetworkIdsByChain('solana');
 // ['solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1', ...]
 ```
 
-## Implementation Details
+## Security Best Practices
 
-This SDK uses the @phantom/openapi-wallet-service package which provides:
-- `createWallet` - Creates a new wallet and retrieves its public key via signRawPayload
-- `signTransaction` - Signs transactions with the wallet's private key
-- `signRawPayload` - Signs raw payloads/messages and returns signature with public key
+- **Never expose your private key** in client-side code or commit it to version control
+- Store your credentials securely using environment variables or secret management systems
+- Each wallet is isolated and can only be accessed by your organization
+- All API requests are authenticated using cryptographic signatures
 
-The SDK handles:
-- Network-specific algorithms and curves automatically
-- Standard derivation paths for each blockchain
-- Base64 encoding for transaction data
-- Authentication via Ed25519 signatures
-- CAIP-2 network ID parsing and submission config derivation
+## Error Handling
 
-## Authentication
-
-The SDK authenticates requests using Ed25519 signatures:
-- Each request is signed with your organization's private key
-- The signature, public key, and timestamp are added as headers
-- This ensures secure communication with the Phantom wallet service
+All SDK methods throw descriptive errors when operations fail:
 
+```typescript
+try {
+  const wallet = await sdk.createWallet();
+} catch (error) {
+  console.error('Failed to create wallet:', error.message);
+}
+```
 
-## Notes
+## Support
 
-- The wallet ID is a UUID assigned by the service when creating the wallet
-- Public keys are retrieved using the signRawPayload method with an empty payload
-- Transaction hashes are not returned by the signing service - they're generated after blockchain submission
-- The service returns the public key that signed the transaction in the signature field
-- Default wallet names include a timestamp to ensure uniqueness
-- Message signing supports both Solana (Ed25519) and Ethereum (Secp256k1) networks
+For detailed integration examples and best practices, see the [Integration Guide](./INTEGRATION.md).

package/dist/constants.d.ts

@@ -1,10 +1,11 @@
 import { DerivationInfoCurveEnum, DerivationInfoAddressFormatEnum, Algorithm } from '@phantom/openapi-wallet-service';
+import { NetworkId } from './caip2-mappings';
 /**
  * Default derivation paths for different blockchain networks
  */
 export declare enum DerivationPath {
     Solana = "m/44'/501'/0'/0'",
-    Ethereum = "m/44'/60'/0'/0",
+    Ethereum = "m/44'/60'/0'/0/0",
     Bitcoin = "m/84'/0'/0'/0",
     Sui = "m/44'/784'/0'/0'/0'"
 }
@@ -24,4 +25,4 @@ export interface NetworkConfig {
 /**
  * Get complete network configuration
  */
-export declare function getNetworkConfig(networkId: string): NetworkConfig;
+export declare function getNetworkConfig(networkId: NetworkId): NetworkConfig | null;

package/dist/constants.js

@@ -12,7 +12,7 @@ var DerivationPath;
     // Solana - BIP44 standard for Solana (coin type 501)
     DerivationPath["Solana"] = "m/44'/501'/0'/0'";
     // Ethereum - BIP44 standard for Ethereum and all EVM-compatible chains (coin type 60)
-    DerivationPath["Ethereum"] = "m/44'/60'/0'/0";
+    DerivationPath["Ethereum"] = "m/44'/60'/0'/0/0";
     // Bitcoin - BIP44 standard for Bitcoin (coin type 0)
     DerivationPath["Bitcoin"] = "m/84'/0'/0'/0";
     // Sui - BIP44 standard for Sui (coin type 784)
@@ -68,7 +68,7 @@ function getNetworkConfig(networkId) {
                 algorithm: openapi_wallet_service_1.Algorithm.secp256k1,
                 addressFormat: openapi_wallet_service_1.DerivationInfoAddressFormatEnum.bitcoinSegwit // Bitcoin uses a different format, but for SDK consistency we use Ethereum format
             };
-        default:
+        case 'eip155': // EVM chains use eip155 prefix
             // All EVM-compatible chains (Ethereum, Polygon, BSC, Arbitrum, etc.)
             return {
                 derivationPath: DerivationPath.Ethereum,
@@ -76,5 +76,7 @@ function getNetworkConfig(networkId) {
                 algorithm: openapi_wallet_service_1.Algorithm.secp256k1,
                 addressFormat: openapi_wallet_service_1.DerivationInfoAddressFormatEnum.ethereum // EVM chains use Ethereum address format
             };
+        default:
+            return null;
     }
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { ServerSDKConfig, CreateWalletResult, Transaction, SignedTransaction } from "./types";
+import { ServerSDKConfig, CreateWalletResult, Transaction, SignedTransaction, GetWalletsResult } from "./types";
+import { NetworkId } from "./caip2-mappings";
 export interface SubmissionConfig {
     chain: string;
     network: string;
@@ -10,11 +11,12 @@ export declare class ServerSDK {
     private signingKeypair;
     constructor(config: ServerSDKConfig);
     createWallet(walletName?: string): Promise<CreateWalletResult>;
-    signAndSendTransaction(walletId: string, transaction: Transaction, networkId: string): Promise<SignedTransaction>;
+    signAndSendTransaction(walletId: string, transaction: Transaction, networkId: NetworkId): Promise<SignedTransaction>;
     getWalletAddresses(walletId: string, derivationPaths?: string[]): Promise<{
         addressType: string;
         address: string;
     }[]>;
-    signMessage(walletId: string, message: string, networkId: string): Promise<string>;
+    signMessage(walletId: string, message: string, networkId: NetworkId): Promise<string>;
+    getWallets(limit?: number, offset?: number): Promise<GetWalletsResult>;
 }
 export * from "./types";

package/dist/index.js

@@ -103,41 +103,37 @@ class ServerSDK {
             if (!submissionConfig) {
                 console.warn(`No submission config available for network ${networkId}. Transaction will be signed but not submitted.`);
             }
-            // For Solana transactions
-            if (networkId.startsWith("solana:")) {
-                // Get network configuration
-                const networkConfig = (0, constants_1.getNetworkConfig)(networkId);
-                const derivationInfo = {
-                    derivationPath: networkConfig.derivationPath,
-                    curve: networkConfig.curve,
-                    addressFormat: networkConfig.addressFormat,
-                };
-                // Sign transaction request - only include submissionConfig if available
-                const signRequest = {
-                    organizationId: this.config.organizationId,
-                    walletId: walletId,
-                    transaction: encodedTransaction,
-                    derivationInfo: derivationInfo,
-                };
-                // Add submission config if available
-                if (submissionConfig) {
-                    signRequest.submissionConfig = submissionConfig;
-                }
-                const request = {
-                    method: openapi_wallet_service_1.SignTransactionMethodEnum.signTransaction,
-                    params: signRequest,
-                    timestampMs: Date.now(),
-                };
-                const response = await this.kmsApi.postKmsRpc(request);
-                const result = response.data.result;
-                return {
-                    rawTransaction: result.transaction, // Base64 encoded signed transaction
-                };
+            // Get network configuration
+            const networkConfig = (0, constants_1.getNetworkConfig)(networkId);
+            if (!networkConfig) {
+                throw new Error(`Unsupported network ID: ${networkId}`);
             }
-            else {
-                // For EVM chains (future implementation)
-                throw new Error("EVM transaction signing not yet implemented");
+            const derivationInfo = {
+                derivationPath: networkConfig.derivationPath,
+                curve: networkConfig.curve,
+                addressFormat: networkConfig.addressFormat,
+            };
+            // Sign transaction request - only include submissionConfig if available
+            const signRequest = {
+                organizationId: this.config.organizationId,
+                walletId: walletId,
+                transaction: encodedTransaction,
+                derivationInfo: derivationInfo,
+            };
+            // Add submission config if available
+            if (submissionConfig) {
+                signRequest.submissionConfig = submissionConfig;
             }
+            const request = {
+                method: openapi_wallet_service_1.SignTransactionMethodEnum.signTransaction,
+                params: signRequest,
+                timestampMs: Date.now(),
+            };
+            const response = await this.kmsApi.postKmsRpc(request);
+            const result = response.data.result;
+            return {
+                rawTransaction: result.transaction, // Base64 encoded signed transaction
+            };
         }
         catch (error) {
             console.error("Failed to sign and send transaction:", error.response?.data || error.message);
@@ -175,19 +171,21 @@ class ServerSDK {
     }
     async signMessage(walletId, message, networkId) {
         try {
-            // Convert message to byte array
-            const messageBytes = Array.from(Buffer.from(message, "utf8"));
             // Get network configuration
             const networkConfig = (0, constants_1.getNetworkConfig)(networkId);
+            if (!networkConfig) {
+                throw new Error(`Unsupported network ID: ${networkId}`);
+            }
             const derivationInfo = {
                 derivationPath: networkConfig.derivationPath,
                 curve: networkConfig.curve,
                 addressFormat: networkConfig.addressFormat,
             };
+            const base64StringMessage = Buffer.from(message, "utf8").toString("base64");
             const signRequest = {
                 organizationId: this.config.organizationId,
                 walletId: walletId,
-                payload: messageBytes,
+                payload: base64StringMessage,
                 algorithm: networkConfig.algorithm,
                 derivationInfo: derivationInfo,
             };
@@ -206,6 +204,36 @@ class ServerSDK {
             throw new Error(`Failed to sign message: ${error.response?.data?.message || error.message}`);
         }
     }
+    async getWallets(limit, offset) {
+        try {
+            const request = {
+                method: "getOrganizationWallets",
+                params: {
+                    organizationId: this.config.organizationId,
+                    limit: limit || 20,
+                    offset: offset || 0,
+                },
+                timestampMs: Date.now(),
+            };
+            console.log("Fetching wallets for organization:", this.config.organizationId);
+            const response = await this.kmsApi.postKmsRpc(request);
+            const result = response.data.result;
+            console.log(`Fetched ${result.wallets.length} wallets out of ${result.totalCount} total`);
+            return {
+                wallets: result.wallets.map((wallet) => ({
+                    walletId: wallet.walletId,
+                    walletName: wallet.walletName,
+                })),
+                totalCount: result.totalCount,
+                limit: result.limit,
+                offset: result.offset,
+            };
+        }
+        catch (error) {
+            console.error("Failed to get wallets:", error.response?.data || error.message);
+            throw new Error(`Failed to get wallets: ${error.response?.data?.message || error.message}`);
+        }
+    }
 }
 exports.ServerSDK = ServerSDK;
 __exportStar(require("./types"), exports);

package/dist/types.d.ts

@@ -17,3 +17,13 @@ export type Transaction = Uint8Array;
 export interface SignedTransaction {
     rawTransaction: string;
 }
+export interface Wallet {
+    walletId: string;
+    walletName: string;
+}
+export interface GetWalletsResult {
+    wallets: Wallet[];
+    totalCount: number;
+    limit: number;
+    offset: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phantom/server-sdk",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Server SDK for Phantom Wallet",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",