@empereur-rouge/pms-sdk 0.2.0 → 0.3.1

package/README.md

@@ -132,6 +132,43 @@ const client = new PmsClient({
 > [!IMPORTANT]
 > La clé API est **obligatoire**. Obtenez-la depuis votre dashboard PMS ou auprès de l'administrateur du réseau.
 
+#### Wallet (Custodial — Server-Side)
+
+Ces méthodes créent/restaurent des wallets **côté serveur**. L'adresse retournée est au format Bech32 (ex: `8e1a...`).
+
+```typescript
+// Créer un nouveau wallet (serveur génère les clés)
+const wallet = await client.createWallet();
+// Réponse (WalletResponse):
+// {
+//   address: "8e1ahpltzjauwev6lf0jql...",
+//   private_key_b64: "2lM0rVdFXX...",
+//   private_key_hex: "da5334ad57455d74...",
+//   public_key_hex: "04593037fa9d4f6ea2...",
+//   x25519_pub_hex: "266bcd33ab2d20d2...",
+//   mnemonic_words: ["gain", "space", "color", ...]
+// }
+```
+
+```typescript
+// Restaurer un wallet depuis un mnemonic (24 mots BIP39)
+const restored = await client.restoreFromMnemonic(
+  "gain space color filter buzz bind side before sauce twist slam history chief patch desk chunk way oblige output turtle purchase scare token rapid"
+);
+console.log(restored.address); // "8e1ahpltzjauwev6lf0jql..."
+```
+
+```typescript
+// Restaurer un wallet depuis une clé privée hex
+const imported = await client.restoreFromPrivateKey(
+  "da5334ad57455d74e5150e4eb06398ce9cf27762b6f29eac7f82f178bee07406"
+);
+console.log(imported.address); // même adresse que ci-dessus
+```
+
+> [!NOTE]
+> Le mnemonic et la clé privée produisent **exactement la même adresse** — la dérivation est déterministe.
+
 #### Méthodes de Lecture
 
 ```typescript
@@ -407,6 +444,7 @@ import type {
   SubmitResponse,
   BalanceInfo,
   SupplyInfo,
+  WalletResponse,
   
   // NFT
   NftMetadata,

package/dist/index.cjs

@@ -415,6 +415,68 @@ var PmsClient = class {
     return res.utxos ?? [];
   }
   // ═══════════════════════════════════════════════════════════════════════
+  // Wallet API (Custodial — Server-Side)
+  // ═══════════════════════════════════════════════════════════════════════
+  /**
+   * Crée un nouveau wallet côté serveur (custodial).
+   * Le serveur génère le wallet et retourne toutes les clés + adresse Bech32.
+   *
+   * @returns Wallet complet avec adresse, clés et mnemonic
+   *
+   * @example
+   * ```typescript
+   * const wallet = await client.createWallet();
+   * console.log(wallet.address);        // "8e1a..."
+   * console.log(wallet.mnemonic_words); // ["gain", "space", ...]
+   * ```
+   */
+  async createWallet() {
+    return this.fetch("/v1/wallet/create", {
+      method: "POST",
+      body: JSON.stringify({})
+    });
+  }
+  /**
+   * Restaure un wallet depuis une phrase mnémonique BIP39 (24 mots).
+   *
+   * @param mnemonic - 24 mots BIP39 séparés par des espaces
+   * @returns Wallet restauré avec adresse, clés et mnemonic
+   *
+   * @example
+   * ```typescript
+   * const wallet = await client.restoreFromMnemonic(
+   *     "gain space color filter buzz bind side before sauce twist slam history chief patch desk chunk way oblige output turtle purchase scare token rapid"
+   * );
+   * console.log(wallet.address); // "8e1a..."
+   * ```
+   */
+  async restoreFromMnemonic(mnemonic) {
+    return this.fetch("/v1/wallet/restore/mnemonic", {
+      method: "POST",
+      body: JSON.stringify({ mnemonic })
+    });
+  }
+  /**
+   * Restaure un wallet depuis une clé privée hexadécimale.
+   *
+   * @param privateKeyHex - Clé privée hex (64 caractères = 32 bytes)
+   * @returns Wallet restauré avec adresse et clés (sans mnemonic)
+   *
+   * @example
+   * ```typescript
+   * const wallet = await client.restoreFromPrivateKey(
+   *     "da5334ad57455d74e5150e4eb06398ce9cf27762b6f29eac7f82f178bee07406"
+   * );
+   * console.log(wallet.address); // "8e1a..."
+   * ```
+   */
+  async restoreFromPrivateKey(privateKeyHex) {
+    return this.fetch("/v1/wallet/restore/private-key", {
+      method: "POST",
+      body: JSON.stringify({ private_key_hex: privateKeyHex })
+    });
+  }
+  // ═══════════════════════════════════════════════════════════════════════
   // Préparation de Transaction (Server-Side)
   // ═══════════════════════════════════════════════════════════════════════
   /**

package/dist/index.d.cts

@@ -460,6 +460,21 @@ interface NftResponse {
     /** @deprecated Les métadonnées sont maintenant chiffrées dans le bloc source */
     metadata?: NftMetadata;
 }
+/** Réponse de création/restauration de wallet (server-side) */
+interface WalletResponse {
+    /** Adresse Bech32 du wallet */
+    address: string;
+    /** Clé privée en base64 */
+    private_key_b64: string;
+    /** Clé privée en hex (64 chars) */
+    private_key_hex: string;
+    /** Clé publique secp256k1 non-compressée (hex) */
+    public_key_hex: string;
+    /** Clé publique X25519 (hex) */
+    x25519_pub_hex: string;
+    /** Mots mnémoniques (24 mots, absent si restauré depuis clé privée) */
+    mnemonic_words?: string[];
+}
 /** Balance d'une adresse */
 interface BalanceInfo {
     /** Adresse */
@@ -602,6 +617,50 @@ declare class PmsClient {
      * Récupère les UTXOs d'une adresse.
      */
     getUtxos(address: string): Promise<Utxo[]>;
+    /**
+     * Crée un nouveau wallet côté serveur (custodial).
+     * Le serveur génère le wallet et retourne toutes les clés + adresse Bech32.
+     *
+     * @returns Wallet complet avec adresse, clés et mnemonic
+     *
+     * @example
+     * ```typescript
+     * const wallet = await client.createWallet();
+     * console.log(wallet.address);        // "8e1a..."
+     * console.log(wallet.mnemonic_words); // ["gain", "space", ...]
+     * ```
+     */
+    createWallet(): Promise<WalletResponse>;
+    /**
+     * Restaure un wallet depuis une phrase mnémonique BIP39 (24 mots).
+     *
+     * @param mnemonic - 24 mots BIP39 séparés par des espaces
+     * @returns Wallet restauré avec adresse, clés et mnemonic
+     *
+     * @example
+     * ```typescript
+     * const wallet = await client.restoreFromMnemonic(
+     *     "gain space color filter buzz bind side before sauce twist slam history chief patch desk chunk way oblige output turtle purchase scare token rapid"
+     * );
+     * console.log(wallet.address); // "8e1a..."
+     * ```
+     */
+    restoreFromMnemonic(mnemonic: string): Promise<WalletResponse>;
+    /**
+     * Restaure un wallet depuis une clé privée hexadécimale.
+     *
+     * @param privateKeyHex - Clé privée hex (64 caractères = 32 bytes)
+     * @returns Wallet restauré avec adresse et clés (sans mnemonic)
+     *
+     * @example
+     * ```typescript
+     * const wallet = await client.restoreFromPrivateKey(
+     *     "da5334ad57455d74e5150e4eb06398ce9cf27762b6f29eac7f82f178bee07406"
+     * );
+     * console.log(wallet.address); // "8e1a..."
+     * ```
+     */
+    restoreFromPrivateKey(privateKeyHex: string): Promise<WalletResponse>;
     /**
      * Prépare une transaction de transfert via le serveur.
      * Le serveur sélectionne les UTXOs et calcule les frais.
@@ -856,4 +915,4 @@ declare function formatAmount(sats: bigint): string;
  */
 declare function decryptPayload(encrypted: EncryptedPayload, recipientPrivateKeyHex: string): string;
 
-export { type BalanceInfo, type Block, type BurnNftResponse, type CoordinatorInfoResponse, type CubeAttributes, type HistoryItem, type MintCubeResponse, type NftMetadata, type NftResponse, PmsClient, type PmsClientConfig, PmsWallet, type PrepareTxRequest, type PrepareTxResponse, type RuntimeConfig, type SubmitResponse, type SupplyInfo, type TokenMetadata, type Utxo, type UtxoDetail, type WalletHistoryResp, decryptPayload, formatAmount, fromHex, isValidMnemonic, parseAmount, toHex };
+export { type BalanceInfo, type Block, type BurnNftResponse, type CoordinatorInfoResponse, type CubeAttributes, type HistoryItem, type MintCubeResponse, type NftMetadata, type NftResponse, PmsClient, type PmsClientConfig, PmsWallet, type PrepareTxRequest, type PrepareTxResponse, type RuntimeConfig, type SubmitResponse, type SupplyInfo, type TokenMetadata, type Utxo, type UtxoDetail, type WalletHistoryResp, type WalletResponse, decryptPayload, formatAmount, fromHex, isValidMnemonic, parseAmount, toHex };

package/dist/index.d.ts

@@ -460,6 +460,21 @@ interface NftResponse {
     /** @deprecated Les métadonnées sont maintenant chiffrées dans le bloc source */
     metadata?: NftMetadata;
 }
+/** Réponse de création/restauration de wallet (server-side) */
+interface WalletResponse {
+    /** Adresse Bech32 du wallet */
+    address: string;
+    /** Clé privée en base64 */
+    private_key_b64: string;
+    /** Clé privée en hex (64 chars) */
+    private_key_hex: string;
+    /** Clé publique secp256k1 non-compressée (hex) */
+    public_key_hex: string;
+    /** Clé publique X25519 (hex) */
+    x25519_pub_hex: string;
+    /** Mots mnémoniques (24 mots, absent si restauré depuis clé privée) */
+    mnemonic_words?: string[];
+}
 /** Balance d'une adresse */
 interface BalanceInfo {
     /** Adresse */
@@ -602,6 +617,50 @@ declare class PmsClient {
      * Récupère les UTXOs d'une adresse.
      */
     getUtxos(address: string): Promise<Utxo[]>;
+    /**
+     * Crée un nouveau wallet côté serveur (custodial).
+     * Le serveur génère le wallet et retourne toutes les clés + adresse Bech32.
+     *
+     * @returns Wallet complet avec adresse, clés et mnemonic
+     *
+     * @example
+     * ```typescript
+     * const wallet = await client.createWallet();
+     * console.log(wallet.address);        // "8e1a..."
+     * console.log(wallet.mnemonic_words); // ["gain", "space", ...]
+     * ```
+     */
+    createWallet(): Promise<WalletResponse>;
+    /**
+     * Restaure un wallet depuis une phrase mnémonique BIP39 (24 mots).
+     *
+     * @param mnemonic - 24 mots BIP39 séparés par des espaces
+     * @returns Wallet restauré avec adresse, clés et mnemonic
+     *
+     * @example
+     * ```typescript
+     * const wallet = await client.restoreFromMnemonic(
+     *     "gain space color filter buzz bind side before sauce twist slam history chief patch desk chunk way oblige output turtle purchase scare token rapid"
+     * );
+     * console.log(wallet.address); // "8e1a..."
+     * ```
+     */
+    restoreFromMnemonic(mnemonic: string): Promise<WalletResponse>;
+    /**
+     * Restaure un wallet depuis une clé privée hexadécimale.
+     *
+     * @param privateKeyHex - Clé privée hex (64 caractères = 32 bytes)
+     * @returns Wallet restauré avec adresse et clés (sans mnemonic)
+     *
+     * @example
+     * ```typescript
+     * const wallet = await client.restoreFromPrivateKey(
+     *     "da5334ad57455d74e5150e4eb06398ce9cf27762b6f29eac7f82f178bee07406"
+     * );
+     * console.log(wallet.address); // "8e1a..."
+     * ```
+     */
+    restoreFromPrivateKey(privateKeyHex: string): Promise<WalletResponse>;
     /**
      * Prépare une transaction de transfert via le serveur.
      * Le serveur sélectionne les UTXOs et calcule les frais.
@@ -856,4 +915,4 @@ declare function formatAmount(sats: bigint): string;
  */
 declare function decryptPayload(encrypted: EncryptedPayload, recipientPrivateKeyHex: string): string;
 
-export { type BalanceInfo, type Block, type BurnNftResponse, type CoordinatorInfoResponse, type CubeAttributes, type HistoryItem, type MintCubeResponse, type NftMetadata, type NftResponse, PmsClient, type PmsClientConfig, PmsWallet, type PrepareTxRequest, type PrepareTxResponse, type RuntimeConfig, type SubmitResponse, type SupplyInfo, type TokenMetadata, type Utxo, type UtxoDetail, type WalletHistoryResp, decryptPayload, formatAmount, fromHex, isValidMnemonic, parseAmount, toHex };
+export { type BalanceInfo, type Block, type BurnNftResponse, type CoordinatorInfoResponse, type CubeAttributes, type HistoryItem, type MintCubeResponse, type NftMetadata, type NftResponse, PmsClient, type PmsClientConfig, PmsWallet, type PrepareTxRequest, type PrepareTxResponse, type RuntimeConfig, type SubmitResponse, type SupplyInfo, type TokenMetadata, type Utxo, type UtxoDetail, type WalletHistoryResp, type WalletResponse, decryptPayload, formatAmount, fromHex, isValidMnemonic, parseAmount, toHex };

package/dist/index.js

@@ -382,6 +382,68 @@ var PmsClient = class {
     return res.utxos ?? [];
   }
   // ═══════════════════════════════════════════════════════════════════════
+  // Wallet API (Custodial — Server-Side)
+  // ═══════════════════════════════════════════════════════════════════════
+  /**
+   * Crée un nouveau wallet côté serveur (custodial).
+   * Le serveur génère le wallet et retourne toutes les clés + adresse Bech32.
+   *
+   * @returns Wallet complet avec adresse, clés et mnemonic
+   *
+   * @example
+   * ```typescript
+   * const wallet = await client.createWallet();
+   * console.log(wallet.address);        // "8e1a..."
+   * console.log(wallet.mnemonic_words); // ["gain", "space", ...]
+   * ```
+   */
+  async createWallet() {
+    return this.fetch("/v1/wallet/create", {
+      method: "POST",
+      body: JSON.stringify({})
+    });
+  }
+  /**
+   * Restaure un wallet depuis une phrase mnémonique BIP39 (24 mots).
+   *
+   * @param mnemonic - 24 mots BIP39 séparés par des espaces
+   * @returns Wallet restauré avec adresse, clés et mnemonic
+   *
+   * @example
+   * ```typescript
+   * const wallet = await client.restoreFromMnemonic(
+   *     "gain space color filter buzz bind side before sauce twist slam history chief patch desk chunk way oblige output turtle purchase scare token rapid"
+   * );
+   * console.log(wallet.address); // "8e1a..."
+   * ```
+   */
+  async restoreFromMnemonic(mnemonic) {
+    return this.fetch("/v1/wallet/restore/mnemonic", {
+      method: "POST",
+      body: JSON.stringify({ mnemonic })
+    });
+  }
+  /**
+   * Restaure un wallet depuis une clé privée hexadécimale.
+   *
+   * @param privateKeyHex - Clé privée hex (64 caractères = 32 bytes)
+   * @returns Wallet restauré avec adresse et clés (sans mnemonic)
+   *
+   * @example
+   * ```typescript
+   * const wallet = await client.restoreFromPrivateKey(
+   *     "da5334ad57455d74e5150e4eb06398ce9cf27762b6f29eac7f82f178bee07406"
+   * );
+   * console.log(wallet.address); // "8e1a..."
+   * ```
+   */
+  async restoreFromPrivateKey(privateKeyHex) {
+    return this.fetch("/v1/wallet/restore/private-key", {
+      method: "POST",
+      body: JSON.stringify({ private_key_hex: privateKeyHex })
+    });
+  }
+  // ═══════════════════════════════════════════════════════════════════════
   // Préparation de Transaction (Server-Side)
   // ═══════════════════════════════════════════════════════════════════════
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@empereur-rouge/pms-sdk",
-    "version": "0.2.0",
+    "version": "0.3.1",
     "description": "TypeScript SDK for PMS (Planetary Monetary System) — wallet management, transactions, NFTs, and DAG interactions",
     "author": "empereur-rouge",
     "license": "MIT",